A.C.E. 2

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 2 / ACE CD 2.iso / FILES / DOCS / REAL3DD.LHA / Real3DPart6.doc < prev next >

Wrap

Text File | 1994-11-27 | 146.8 KB | 7,732 lines

PART 6 - REFERENCE 3.4 - WORD > TEMPLATE i2 i1 > IResult DESCRIPTION Takes two integer values off the stack and compares them. If the second value is greater than the first value, > puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE 10 20 >.(0 10 5 >.(1 WORD >= TEMPLATE i2 i1 >=IResult DESCRIPTION Takes two integer values off the stack and compares them. If the second value is greater than or equal to the first value, >= puts TRUE on the stack, otherwise FALSE is put on the stack. EXAMPLE : IsNegative (val) 0>= IF "yes"PUTS ELSE "no"PUTS ENDIF ; 10 IsNegative (no -1 IsNegative (yes 0 IsNegative (no WORD >R TEMPLATE e>R DESCRIPTION Takes the stack top values and stores it on the Return Stack as an integer value. SEE ALSO R> WORD >RAD TEMPLATE fDeg >RAD fRad DESCRIPTION Converts a value given in degrees to radians. EXAMPLE 180.0>RAD F.(3.141593 WORD ?& TEMPLATE ?& name a DESCRIPTION Retrieves the address of a given word. If the word is not found pushes a 0 onto the stack. - REFERENCE 3.5 - EXAMPLE : DO_IF_FOUND ( executes word DOIT ( if it has been defined DOIT ?& ?DUP IF EXECUTE ENDIF ; SEE ALSO & EXECUTE WORD ?DUP TEMPLATE e ?DUP e e DESCRIPTION Duplicates the stack top value if it is not zero. SEE ALSO DUP WORD ?ELSE TEMPLATE ?ELSE DESCRIPTION In an interactive conditional structure marks the beginning of the block that is to be executed when the condition fails (i.e the flag tested is FALSE). SEE ALSO ?ENDIF ?IF ELSE ENDIF IF EXAMPLE ( define constant if not yet defined ) ?& MyVar NOT ?IF 1 CONSTANT MyVar ?ENDIF WORD ?ENDIF TEMPLATE ?ENDIF DESCRIPTION Ends an interactive conditional structure, either ?IF..?ENDIF or ?IF...?ELSE. .?ENDIF. SEE ALSO ?ELSE ?IF ELSE ENDIF IF WORD ?IF TEMPLATE I ?IF DESCRIPTION Begins an interactive conditional structure, . either ?IF..?ENDIF or ?IF..?ELSE..?ENDIF. If the flag is TRUE then the words entered after ?IF will be executed immediately until either ?ELSE or ?ENDIF is encountered. If the flag is FALSE, the words between ?IF and ?ELSE/?ENDIF are ignored. Execution then resumes after ?ELSE/?ENDIF. The interactive conditional structure remains active until ?ENDIF is encountered. These interactive conditional structures may be nested. - REFERENCE 3.6 - Note: Interactive conditional structures can be used to control the execution of parts of an RPL file as it is loaded. EXAMPLE ( check if the word VADD is already defined ) ?& VADD ?IF "vectors.rpl already installed" PUTS ?ELSE "vectors.rpl" LOAD ?ENDIF SEE ALSO ?ELSE ?ENDIF ELSE ENDIF IF WORD @ TEMPLATE aInteger @ iValue DESCRIPTION Fetches the value of an integer variable and puts the value on the stack top. The address of the integer variable must be on the stack top before calling this word. EXAMPLE ( MyVar = MyVar + 1 ) MyVar @ 1 + MyVar @ ! SEE ALSO ! VARIABLE WORD AGAIN TEMPLATE AGAIN DESCRIPTION Marks the end of an BEGIN..AGAIN loop. The BEGIN..AGAIN loop executes forever unless a QUIT or EXIT is executed. Note: Can only be used inside a word definition. EXAMPLE : MyLoop BEGIN "YESlNO'" "Cancel Loop ?" GET_KEY IF EXIT ENDIF AGAIN ; SEE ALSO BEGIN EXIT QUIT WORD AND TEMPLATE I2 I1 AND I DESCRIPTION Takes two boolean flags off the stack and, if they both are TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. The value is TRUE if it is not zero. - REFERENCE 3.7 - SEE ALSO IF OR XOR EXAMPLE 1 1 AND . ( 1 0 1 AND . ( 0 0 0 AND . ( 0 10 20 AND . ( 1 WORD ACOS TEMPLATE fRad ACOS fAng RETURNS fAng - value from 0 to PI DESCRIPTION Arccosine function. EXAMPLE 0.5 ACOS F. SEE ALSO ASIN, ATAN, COS WORD ASIN TEMPLATE fRad ASIN fAng RETURNS fAng - value from -PI/2 to PI/2 DESCRIPTION Arcsine function. EXAMPLE 0.5 ASIN F. SEE ALSO ACOS, ATAN, COS WORD ATAN TEMPLATE fRad ATAN fAng RETURNS fAng - value from -PI/2 to PI/2 DESCRIPTION Arctangent function. SEE ALSO ASIN, ACOS, TAN WORD B. TEMPLATE iB. DESCRIPTION Takes an integer off the stack and prints it as a binary number. - REFERENCE 3.8 - SEE ALSO .H.O. EXAMPLE 1 B. (00000000000000000000000000000001 2 B. (00000000000000000000000000000010 3 B. (00000000000000000000000000000011 4 B. (00000000000000000000000000000100 - WORD B! TEMPLATE b aByte B! DESCRIPTION Stores a value in a byte variable. Takes the address of the variable and the value to be stored off the stack. Note: There are no byte variables in RPL. This word is needed only when accessing 8 bit data (like R,G,B) from data structures. SEE ALSO W! W@ B@ WORD B@ TEMPLATE aByte B@ iValue DESCRIPTION Fetches the value of a byte. The address of the byte must be in the stack top before calling this word. Note: See Note: for B!. SEE ALSO W! W@ B! WORD BAND TEMPLATE i2 i1 BAND i DESCRIPTION Makes a binary AND operation on the two operands and puts the result on the stack. In a binary AND operation, the result has only those bits set whose corresponding bits are set in both the operands. SEE ALSO BNOT BOR BXOR EXAMPLE 1 1 BAND (1 2 1 BAND (0 2 3 BAND (3 - REFERENCE 3.9 - WORD BEGIN TEMPLATE BEGIN DESCRIPTION BEGIN marks the beginning of an indefinite loop. An indefinite loop can be any of the following: BEGIN..UNTIL BEGIN . .AGAIN BEGIN..WHILE..REPEAT In the BEGIN..UNTIL loop a flag is tested at the end of each repetition of the loop. If the flag is TRUE, the loop terminates. Otherwise the loop repeats. Since the test is made at the end of the loop, the loop will always be executed at least once. The BEGIN..AGAIN loop executes forever unless a QUIT or EXIT is executed. In the BEGIN..WHILE..REPEAT loop the words between BEGIN and WHILE are first executed, and then a flag is tested. If the flag is TRUE, the words between WHILE and REPEAT are executed and the loop starts over. If the flag is FALSE, then execution skips to the word that comes after REPEAT. Indefinite loops can be nested. Note: Can only be used inside a word definition. SEE ALSO UNTIL AGAIN WHILE REPEAT QUIT EXIT EXAMPLE : BeginUntil BEGIN "YeslNo" "Cancel Loop ?" GET_KEY UNTIL ; : BeginAgain BEGIN "YeslNo" "Cancel Loop ?" GET_KEY IF QUIT ENDIF AGAIN ; : BegWhlRpt BEGIN "YeslNo" "Continue ?" GET_KEY WHILE "hello" PUTS REPEAT ; WORD BNOT TEMPLATE i1 BNOT i DESCRIPTION Inverts the bits of a integer value on the stack. Any bits in the integer value that are set (1) are reset, and any bits that are reset (0) are set. SEE ALSO BAND BOR BXOR - REFERENCE 3.10 - WORD BOR TEMPLATE i2 i1 BOR i DESCRIPTION Makes a binary OR operation on the two operands and puts the result on the stack. In a binary OR operation the result has all those bits set that have a corresponding bit set in either or both of the operands. SEE ALSO BNOT BAND BXOR WORD BXOR TEMPLATE i2 i1 BXOR i DESCRIPTION Makes a binary XOR (exclusive or) operation on the two operands and puts the result on the stack. In a binary XOR operation the result has those bits set that have a corresponding bit set in only one of the operands. SEE ALSO BNOT BAND BOR WORD CAT TEMPLATE s2 s1 CAT DESCRIPTION Concatenates two strings. Takes two pointers s1 and s2, and joins the string pointed to by s2 to the end of string pointed to by s1. The result is stored in s1. EXAMPLE 30 STRING NAME "Mary" NAME CPY " Smith" NAME CAT NAME PUTS SEE ALSO CPY PUTS SPRINTF STRING WORD CONSTANT TEMPLATE i CONSTANT name DESCRIPTION Defines a named integer constant and initializes it to the value popped off the stack. When the constant is later referenced by entering it's name, the value of the constant is pushed onto the stack. Note: This word is usually used outside word definitions. - REFERENCE 3.11 - SEE ALSO VARIABLE FVARIABLE FCONSTANT WORD COS TEMPLATE f1 COS f DESCRIPTION Calculates the cosine of the stack top item. The operand must be in radians. SEE ALSO SIN EXAMPLE 3.16 SIN F. WORD CPY TEMPLATE s2 s1 CPY DESCRIPTION Copies a string. Takes two pointers s1 and s2, and copies the string pointed to by s2 to the string pointed to by s1. SEE ALSO CAT PUTS SPRINTF STRING EXAMPLE 100 STRING sBuf "Hello world" sBuf CPY sBuf PUTS WORD DEPTH TEMPLATE DEPTH i DESCRIPTION Puts the count of the stack items onto the stack. SEE ALSO RDEPTH WORD DO TEMPLATE i2 i1 DO DESCRIPTION Begins a definite loop, either DO..LOOP or DO..+LOOP A definite loop executes the words inside the loop a specified number of times. The beginning (i1) and ending (i2) values for the loop variable are put on the stack before the word DO. The loop variable can be referenced using the words I, J or K depending on the nesting level. Note: Can only be used inside a word definition. - REFERENCE 3.12 - EXAMPLE : 5Times 5 0 DO I . LOOP ; SEE ALSO LOOP +LOOP I J K WORD DROP TEMPLATE e DROP DESCRIPTION Removes the top value from the stack. WORD DUP TEMPLATE e DUP e e DESCRIPTION Duplicates the stack top value retaining its type (i.e. integer or floating-point). SEE ALSO ?DUP WORD ELSE TEMPLATE ELSE DESCRIPTION In a conditional structure, marks the beginning of the block that is to be executed when the condition fails (i.e the flag tested is FALSE). Note: Can only be used inside a word definition. EXAMPLE : ABS ( i ABS i ) DUP 0 >= IF ELSE -1 * ENDIF ; SEE ALSO IF ENDIF WORD EMIT TEMPLATE i EMIT DESCRIPTION Prints the ASCII character corresponding to the first byte of the top stack value. - REFERENCE 3.13 - EXAMPLE : CR 13 EMIT 10 EMIT ; ( carriage return and line feed ) "Hello" PUTS CR "World" PUTS CR WORD ENDIF TEMPLATE ENDIF DESCRIPTION Ends a conditional structure, either IF..ENDIF or IF..ELSE..ENDIF. Note: Can only be used inside a word definition. SEE ALSO IF ELSE WORD ERROR TEMPLATE sErrorMsg ERROR PARAMETERS sErrorMsg - error message to be printed DESCRIPTION Terminates the program as if an error had occurred and prints out the given error message. RPL programs can use this word for terminating code execution in situations which are not interpreted as errors by RPL. For example, if a procedural texture handler realizes that it cannot generate required color information for the renderer, it can call this word in order to cancel rendering. If the sErrorMsg is 0, no error message is printed. EXAMPLE RX RC @ IF "Return value is not zero" ERROR ENDIF WORD EVAL TEMPLATE sExpr EVAL f DESCRIPTION Evaluates an algebraic expression contained in the string pointed to by sExpr, and pushes the result on the stack. If the string contains multiple expressions then the last one evaluated determines the return value. - REFERENCE 3.14 - The following operators are supported by the EVAL word: , - separator for multiple expressions ( - parentheses for controlling evaluation precedence ) - + - add - - subtract * - multiply / - divide - - negate ^ - power % - modulo += - x+=0.1 is same as x = x + 0.1 -= - *= - /= - && - logical AND II - logical OR = - assignment == - comparison is equal > - comparison greater than < - >= - comparison greater or equal <= - != - comparison not equal =if() - =if(a>b,t,f) if a > b then return t, otherwise f abs() - absolute value, for example abs(-10) produces 10 ceil() - returns smallest integer value which is >= x data() - interface to object and material data structures. exp() - exp(x) returns e^x floor() - greatest integer value which is <= x Ig() - log to base 10 In() - natural log max() - returns the greatest from the list min() - min(a,b,c,1,2) returns the smallest from the list a,b,c etc. sgn() - sign, sgn(x) is -1 if x < 0, 0 if x = 0 and 1 if x > 0 sqrt() - square root sum() - sum(1,2,3) = 6 cos() - trigonometric functions sin() - tan() - acos() - inverse trigonometric functions asin() - atan() - ceil() & floor() examples: ceil(1.4) returns 2, floor(1.4) returns 1 and ceil(-1.4) returns -1 data() By using the data() operator of EVAL, the properties of objects and materials and some global system values can be accessed. THE APPROPRIATE DATA STRUCTURE MUST BE LOCKED USING O LOCK OR MAT LOCK BEFORE USING THE data() OPERATOR TO ACCESS THEM. Objects The syntax for accessing object attributes through EVAL is: "data(/path/name->prop)" EVAL f EVAL again returns the address of the property if used without any expression assignment. Where: "/path/name" - Objects name including full absolute path. If the first character in data() is a slash, the name is assumed to refer to an object. Otherwise it is considered to be a material reference. - REFERENCE 3.15 - "prop" - One of the following: R, G, B - Red, Green, or Blue color signal (0 .. 255) A - Alpha information reg - A register color for wire frame representation ptrn - A pattern for the line. Value must be between 0 and 65535 and each bit in pattern represents one pixel in the line to be drawn. If the first bit is set, then the first pixel in the line will be set. Thus a value of 65536 produces a solid line. Materials The syntax is as follows: "data(name->prop)" EVAL f If used without any expression assignment then EVAL will return the address of the material property. Where: "name" - The name of the material in the Material Library to be accessed. "prop" - Any of the material properties listed below: name - name (string field) imag - image (string field) splu - spline mapping u/v/width/height (0.0 .. 1.0) splv splw splh frex - texture frequency x (positive integer) frey - texture frequency y (positive integer) tr.r - transparency color R, G, B (0 .. 255) tr.g tr.b spec - specularity sbri - specular brightness bril - brilliance tran - transparency turb - turbidity tbsa - turbidity saturation refr - refraction roug - roughness dith - dithering scale bump - bump height (-100 .. 100) effc - effect maph - mapping handler mapa - constants for the mapping handler (floating-point) mapb scoh - scope handler scoa scob bmph - bump handler bmpa bmpb colh - color handler cola colb indh - index handler inda indb Values for all properties can vary between 0 .. 100, unless otherwise specified above. Handlers can contain values 0,1. 2 etc. depending on the number of choices in the corresponding cycle gadget in the Material Editor window (Default = 0, etc.). - REFERENCE 3.16 - Global Data Global system data can also be accessed through EVAL. The following variables are defined for this purpose: T - Current Time (floating-point value) Res - Animation Resolution for animation (integer) Frm - Current Animation Frame (integer) EXAMPLE FVARIABLE X 0.02 X F! "0.5 * sin(2 * X) + cos(X)" EVAL F. "Real:Textures/wood1" "data(wood->image)" EVAL CPY "data(/Root/rectangle->R)=255" EVAL ( print out the number of frames ) "Res" EVAL F. ( reset the frame counter and discard ) "Frm=0" EVAL DROP ( the return value ) WORD EXECUTE TEMPLATE aCFA EXECUTE DESCRIPTION Executes a word given it's CFA. SEE ALSO &?& WORD EXIT TEMPLATE EXIT DESCRIPTION Terminates the execution of the current word, and returns control to the word that executed the current word. Note: Can only be used inside a word definition. EXAMPLE : TEST DUP 5 < IF DROP EXIT ENDIF . ; : LUP 10 0 DO I TEST LOOP ; SEE ALSO QUIT WORD EXP TEMPLATE fPar EXP fRet DESCRIPTION Raises the natural logarithm base E to the fPar power. - REFERENCE 3.17 - WORD F. TEMPLATE f F. DESCRIPTION Takes a floating-point value off the stack and prints it. SEE ALSO .H.O.B. WORD F! TEMPLATE f aFloat F! DESCRIPTION Stores a value in a floating-point variable. Takes the address of the variable and the value to be stored off the stack. Note: See the Note: on ! SEE ALSO F@ FVARIABLE WORD F+ TEMPLATE f2f1F+f DESCRIPTION Takes two floating-point values off the stack, adds them, and puts the sum on the stack. WORD F- TEMPLATE f2 f1 F- f DESCRIPTION Takes two integers off the stack, subtracts the stack top value from the second one, and puts the difference on the stack. WORD F* TEMPLATE f2 f1 F* f DESCRIPTION Takes two floating-point values off the stack, multiplies them, and puts the product on the stack. WORD F/ TEMPLATE f2 f1 F/ f DESCRIPTION Takes two floating point values off the stack, divides the second value on the stack by the stack top item, and puts the quotient on the stack. - REFERENCE 3.18 - WORD F< TEMPLATE f2 f1 F< I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is less than the first value, F < puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F<= TEMPLATE f2 f1 F<= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is less than or equal to the first value, F<= puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F<> TEMPLATE f2 f1 F<> I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is not equal to the first value, F <> puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F= TEMPLATE f2 f1 F= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the values are equal, F= puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F> TEMPLATE f2 f1 F> I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is greater than the first value, F > puts TRUE on the stack, otherwise FALSE is put on the stack. WORD F>= TEMPLATE f2 f1 F>= I DESCRIPTION Takes two floating-point values off the stack and compares them. If the second value is greater than or equal to the first value, F>= puts TRUE on the stack, otherwise FALSE is put on the stack. - REFERENCE 3.19 - WORD F>I TEMPLATE f F>I i DESCRIPTION Takes a floating point value off the stack and pushes a corresponding integer value on the stack. SEE ALSO I>F WORD F@ TEMPLATE aFloat F@ f DESCRIPTION Fetches the value of a floating-point variable and puts the value on the stack top. The address of the floating-point variable must be on the stack top before calling this word. Note: See the Note: on ! SEE ALSO F! FVARIABLE WORD FCONSTANT TEMPLATE f FCONSTANT name DESCRIPTION Defines a named floating-point constant and initializes it to the value popped off the stack. When the constant is later referenced by entering it's name, the value of the constant is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO FVARIABLE VARIABLE CONSTANT WORD FMOD TEMPLATE f2 f1 FMOD f DESCRIPTION Takes two floating point values off the stack, divides the second value on the stack by the stack top item, and puts the remainder of the division on the stack. WORD FORGET TEMPLATE FORGET name DESCRIPTION Removes definitions from the vocabulary. All words that have been defined after the given word, as well as the word itself, are removed from the Vocabulary Stack. - REFERENCE 3.20 - WORD FVARIABLE TEMPLATE FVARIABLE name DESCRIPTION Defines a named floating-point variable. The name of the variable must follow the word FVARIABLE. The RPL interpreter allocates memory from the Vocabulary Stack for storing the variable. The variable is initialized as 0.0. When the variable is later referenced by entering it's name, the address of the memory location that stores the variable's value is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO F! F@ FCONSTANT VARIABLE CONSTANT WORD H. TEMPLATE i H. DESCRIPTION Takes an integer off the stack and prints it as a hexadecimal number. SEE ALSO .O.B. WORD I TEMPLATE I i DESCRIPTION Inside a definite loop copies the value of the loop variable of the innermost loop onto the stack. Note: Can only be used inside a word definition. SEE ALSO J K WORD I>F TEMPLATE i I>F f DESCRIPTION Takes an integer value off the stack and pushes a corresponding floating-point value onto the stack. SEE ALSO F>I WORD IF TEMPLATE I IF - REFERENCE 3.21 - DESCRIPTION Begins a conditional structure, either IF..ENDIF or IF..ELSE..ENDIF. In the former case, if the flag is TRUE then the words between IF and ENDIF are executed, and then the words after ENDIF. If the flag is FALSE, execution skips the words between IF and ENDIF. In the latter case, if the flag is TRUE then the words between IF and ENDIF are executed and then the words after ENDIF. If the flag is FALSE, the words between ELSE and ENDIF are executed and then the words after ENDIF. Conditional structures may be nested. Note: Can only be used inside a word definition. EXAMPLE : PrintSign DUP 0 < IF DROP "-" PUTS ELSE 0 > IF "+" PUTS ENDIF ENDIF ; -2 PrintSign 3 PrintSign 0 PrintSign SEE ALSO ELSE ENDIF WORD J TEMPLATE J i DESCRIPTION Inside a definite loop copies the value of the loop variable of the second innermost loop onto the stack. Note: Can only be used inside a word definition. EXAMPLE ( line feed and carriage return ) : CR 10 EMIT 13 EMIT ; : MULT TABLE 11 1 DO 11 1 DO I J * . LOOP CR LOOP ; SEE ALSO I K WORD K TEMPLATE K i DESCRIPTION Inside a definite loop copies the value of the loop variable of the third innermost loop onto the stack. - REFERENCE 3.22 - Note: Can only be used inside a word definition. SEE ALSO I J WORD LEAVE TEMPLATE LEAVE DESCRIPTION Terminates a definite loop prematurely. The word LEAVE causes the definite loop to terminate at the next LOOP or +LOOP. Note: Can only be used inside a word definition. EXAMPLE ( terminates when I squared exceeds 50 ) : LUP 10 0 DO I DUP * DUP 50 > IF LEAVE ELSE DROP ENDIF . LOOP ; SEE ALSO EXIT QUIT WORD LOAD TEMPLATE sFile LOAD DESCRIPTION Loads a file containing RPL code. The effect is the same as if the text had been entered in the RPL window. The address of the string containing the file name is taken off the stack top. WORD LOG TEMPLATE fPar LOG fRet PARAMETER fPar - positive parameter value DESCRIPTION Takes the base E logarithm. The parameter fPar must be a positive value. SEE ALSO LOG10 WORD LOG10 TEMPLATE fPar LOG10 fRet PARAMETER fPar - positive parameter value - REFERENCE 3.23 - DESCRIPTION Takes the base 10 logarithm. The parameter fPar must be a positive value. SEE ALSO LOG WORD LOOP TEMPLATE LOOP DESCRIPTION Ends a definite DO..LOOP loop. Note: Can only be used inside a word definition. SEE ALSO DO +LOOP I J K WORD +LOOP TEMPLATE i +LOOP DESCRIPTION Ends a definite DO.. +LOOP loop. This word is used when the loop variable must be incremented by values other than 1. +LOOP takes the stack top value and adds it to the loop variable. If the ending value is greater than the beginning value, then the loop is exited if the loop variable becomes greater than or equal to the ending value. If the ending value is less than the beginning value, then the DO..+LOOP is exited when the loop variable becomes less than or equal to the ending value. Note: Can only be used inside a word definition. EXAMPLE ( use negative increment ) : Down DO I. -1, + LOOP; 0 5 Down SEE ALSO DO LOOP I J K WORD MOD TEMPLATE i2 i1 MOD i DESCRIPTION Takes two integers off the stack, divides the second value on the stack by the stack top item, and puts the remainder of the division on the stack. WORD NOT TEMPLATE I1 NOT I2 - REFERENCE 3.24 - DESCRIPTION Inverts a boolean value on the stack. If the flag is TRUE, it is replaced by FALSE and vice versa. Any value that is not equal to zero is regarded as TRUE. A value of zero is regarded as FALSE. SEE ALSO IF WORD O. TEMPLATE iO. DESCRIPTION Takes an integer off the stack and prints it as an octal number. SEE ALSO .H.B. WORD OR TEMPLATE I2 I1 OR I DESCRIPTION Takes two boolean flags off the stack and, if either one (or both) is TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. SEE ALSO IF AND XOR WORD OVER TEMPLATE e2 e1 OVER e2 e1 e2 DESCRIPTION Copies the second stack item to the stack top. SEE ALSO ROT ROLL PICK SWAP WORD PICK TEMPLATE i PICK e DESCRIPTION Gets a copy of a value on the stack. The copied value will be the i'th value BEFORE the operand for PICK was entered. EXAMPLE 10 9 8 7 .S 4 PICK .S SEE ALSO ROLL ROT SWAP OVER WORD POW TEMPLATE fPow fVal POW fRet - REFERENCE 3.25 - DESCRIPTION Raises fVal to the fPow power. EXAMPLE 2 3 POW . ( 9 3 4 POW . ( 64 WORD PUTS TEMPLATE sPUTS DESCRIPTION Prints a string pointed to by s. SEE ALSO CAT CPY SPRINTF STRING WORD QUIT TEMPLATE QUIT DESCRIPTION QUIT terminates execution of the current word, empties all stacks and returns control to the interpreter. Note: Can only be used inside a word definition. SEE ALSO EXIT WORD RO TEMPLATE RO i DESCRIPTION Puts on the stack the starting address of the return stack. This is the address where the first item (usually a return address) on return stack is stored. SEE ALSO RDEPTH WORD R> TEMPLATE R> i DESCRIPTION Takes an integer value off the return stack and pushes it onto the Operand Stack. SEE ALSO >R WORD RANDOM TEMPLATE RANDOM f - REFERENCE 3.26 - DESCRIPTION Returns a floating-point value between 0.0 and 1.0 inclusive and pushes it onto the stack. WORD RDEPTH TEMPLATE RDEPTH i DESCRIPTION Puts on the stack the count of the items on the return stack. SEE ALSO DEPTH WORD REPEAT TEMPLATE REPEAT DESCRIPTION Marks the end of a BEGIN..WHILE..REPEAT loop. Note: Can only be used inside a word definition. SEE ALSO BEGIN WHILE - REFERENCE 3.27 - WORD ROLL TEMPLATE described below DESCRIPTION The word ROLL is used to rotate a given number (i) of stack items so that the i'th stack item becomes the stack top item and all the items between the first and the i'th item are moved one position deeper in the stack. The count i is on the stack top before executing ROLL. EXAMPLE 10 9 8 7 .S 3 ROLL .S SEE ALSO PICK ROT SWAP OVER WORD ROT TEMPLATE e3 e2 e1 ROT e1 e3 e2 DESCRIPTION ROT rotates the three topmost stack values so that the third item becomes the top item, and the first and the second item (counting from the stack top) will be the second and the third stack item, respectively. SEE ALSO ROLL SWAP OVER PICK - REFERENCE 3.25 - WORD SO TEMPLATE SO i DESCRIPTION Puts on the stack the starting address of the operand stack. This is the address where the first item on operand stack is stored. SEE ALSO DEPTH WORD SIN TEMPLATE f1 SIN f2 DESCRIPTION Calculates the sine of the stack top item. The operand must be in radians. SEE ALSO COS WORD SQRT TEMPLATE fVal SQRT fRet PARAMETER fVal - Positive value DESCRIPTION Squareroot of fVal. EXAMPLE 9 SQRT . ( 3 16 SQRT . ( 4 WORD SPRINTF TEMPLATE e .. sFormat sResult SPRINTF DESCRIPTION This formats the operand list e . . using the format string specified by sFormat and stores the result in the string whose address is sResult. The operand list must be in REVERSE order as for all RPL word operands. The format string s1 controls the output format as follows: % start conversion specification. Then any of the following: - left adjust operand in its field. m digit string specifying minimum field width. . separator from field width and next digit string. n digit string specifying maximum number of characters or floating-point precision. Then a conversion character: c Operand is taken as a single character. d Operand is converted to decimal notation. - REFERENCE 3.28 - e Operand is taken as floating-point and converted to decimal. f Operand is taken a floating-point and output as [-]mm.nnn where the number of digits for nnn is specified by the precision. g Use %e or %f whichever is shorter. o Operand is converted to unsigned octal notation. s Operand must be a string, and is stored until precision specification or the end of the string is reached. u Operand is converted to unsigned decimal notation. x Operand is converted to unsigned hexadecimal notation. Note: For more information about this word refer to a "C" Language reference manual. EXAMPLE 80 STRING Buffer 31 "Hello, I am %d years old" Buffer SPRINTF Buffer PUTS SEE ALSO CPY CAT PUTS STRING WORD STRING TEMPLATE i STRING name DESCRIPTION Allocates memory for a named string variable. The size of the memory to be allocated is popped off the stack. When the string variable is later referenced by entering it's name, the address of the first character of the string is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO CPY CAT PUTS SPRINTF WORD SWAP TEMPLATE e2 e1 SWAP e1 e2 DESCRIPTION Changes the order of the two stack top values. SEE ALSO ROT ROLL PICK OVER WORD TAN TEMPLATE f1 TAN f2 DESCRIPTION Tangent function SEE ALSO SIN, COS - REFERENCE 3.29 - WORD UNTIL TEMPLATE I UNTIL DESCRIPTION Marks the end of a BEGIN..UNTIL loop. In the BEGIN..UNTIL loop a flag is tested at the end of each repetition of the loop. If the flag is TRUE, the loop terminates. Otherwise the loop repeats. Since the test is made at the end of the loop, the loop will always be executed at least once. Note: Can only be used inside a word definition. EXAMPLE ( scan through a list terminated by zero ) : ListScan BEGIN DUP DUP = IF .H ENDIF NOT UNTIL ; SEE ALSO BEGIN WORD VARIABLE TEMPLATE VARIABLE name DESCRIPTION Defines a named integer variable. The name of the variable must follow the word VARIABLE. RPL interpreter allocates memory from the Vocabulary Stack for storing the variable. The variable is initialized as 0. When the variable is later referenced by entering it's name, the address of the memory location that stores the variable's value is pushed onto the stack. Note: This word is usually used outside word definitions. SEE ALSO ! @ CONSTANT FVARIABLE FCONSTANT WORD VLIST TEMPLATE VLIST DESCRIPTION Lists the names of all words on Vocabulary Stack. WORD W! TEMPLATE w aWord W! - REFERENCE 3.30 - DESCRIPTION Stores a value in an short integer variable. Takes the address of the variable and the value to be stored off the stack. This word can be used for accessing 16 bit integer fields, such as found from Real 3D's material and object data structures. Note: There are no word variables in RPL. This word is needed only when accessing 16 bit data from external data structures. SEE ALSO W@ B@ B! WORD W@ TEMPLATE aWord W@ i DESCRIPTION Fetches the value of a short integer. The address of the integer must be on the stack top before calling this word. Note: See Note: for W!. SEE ALSO W!B@B! WORD WHILE TEMPLATE WHILE DESCRIPTION In a BEGIN..WHILE..REPEAT loop a flag is tested at the WHILE word. If the flag is TRUE, the words between WHILE and REPEAT are executed and the loop starts over. If the flag is FALSE, then execution skips to the word that comes after REPEAT. Note: Can only be used inside a word definition. EXAMPLE : TILL_TEN ( i TIL_TEN ) BEGiN DUP 1 + 10 <= WHILE . REPEAT DROP ; SEE ALSO BEGIN REPEAT WORD XOR TEMPLATE I2 I1 XOR I - REFERENCE 3.31 - DESCRIPTION Takes two boolean flags off the stack and, if one and only one of them is TRUE, puts TRUE on the stack, otherwise puts FALSE on the stack. SEE ALSO IF AND OR 3.2 OBJECT CREATION WORDS The following words allow all the REAL 3D objects to be created using RPL. These creation words can be recognized easily from the prefix "C_". The general syntax for all the creation words is the following: Geometry Color Attributes Tags C_XXXXX Address RPL constants required by these words are defined in the file "creation.rpl". The object data structure must be exclusively locked before using any of these words. 3.2.1 Geometry The structure of this section depends on the object in question and some objects like "links" and "levels" don't have this section at all. The purpose of this section is to describe the geometry for the object to be created. Although the structure is this section is different for all objects, they include some common data. 3.2.1.1 fStAngle & fEnAngle These parameters describe the angle of the sector in terms of the object space of the primitive starting from fStAngle around anti-clockwise to fEnAngle. These two floating-point operands are optional. If a sector primitive is required then bit 12 of iAttr must be set and these two operands must be supplied. Only the following quadric primitives can be sectored: cone cut-cone cylinder ellipse ellipse-segment hyperboloid 3.2.1.2 wGeomFlags This parameter describes additional geometry information for freeforms. wGF_CLOSEU - u dimension periodic: 0 - open, 1 - closed wGF_CLOSEV - v dimension periodic: 0 - open, 1 - closed wGF_SECTOR - set if sector primitive wGF_PERIODIC - open/closed evaluation for animations wGF_CLOSEU and wGF_CLOSEV flags can be used for closing freeform objects. If the flag is set, the curve/surface is closed in corresponding direction. Note: That curves are only sensitive to the flag wGF_CLOSEU. - REFERENCE 3.32 - The wGF_SECTOR flag is set whenever the object is sector primitive. This flag tells to the evaluation system whether or not to treat the primitive as a sector. If the flag wGF_PERIODIC is set, closed curves are evaluated so that their end point is the same as their beginning point. In order to use closed loops for generating continous motions for loop-animations, set this flag. 3.2.1.3 wFreeType This specifies how the point data of a freeform is evaluated: wFT_POLYGON - polygonal line or surface wFT_PHONG - phong shaded surface (treated as polygonal for lines) wFT_BSPLINE - Cubic B-Spline curve/surface All other types are RESERVED. These freeform types correspond the radio-button gadgets in the Modify/ Freeform/Type requester. 3.2.2 iColor This section consists of four integer values defining a color for the object to be created. Whether or not this section should exists, depends on the object in question. The RPL format of this section is the following: bR bG bB bA ( Red Green Blue Alpha ) 3.2.3 Attributes This section is required by all creation words. The attributes data section consists of two different parameters: 3.2.3.1 Name The name of the object to be created can be up to 16 characters long. If a longer string is supplied, it will be truncated. 3.2.3.2 Object Flags The flags field is an integer value containing "yes/no" (on/off) kind of information for the object to be created. The bits in this parameter correspond the gadgets in the requester Modify/Properties/Attributes. Flag Description IOF_INVERTED Volume inverted in Boolean Operations IOF_PAINTED Surface properties affects in Booleans IOF_WFINVISIBLE Wire frame is invisible IOF_LIGHTSOURCE Object is a light source IOF_HOLLOW Represented as a surface instead of solid object IOF_INFINITE Infinite object IOF_SCENE Invisible in primary ray tracing IOF_RTINVISIBLE Ray tracing invisible IOF_NOBP1 No 1 st. bounding plane IOF_NOBP2 No 2nd bounding plane IOF_TEXTURE Primitive used for mapping textures to Absolute Space IOF SECTOR Sector Primitive IOF_PROTECTED Primitive cannot be modified IOF_SEGMENT Segment instead of sector IOF_NOTREFL Not reflected IOF_MOTION Motion Blurred object IOF_SHAdOWLESS Does not Cast Shadows IOF_MATTE Matte Object - REFERENCE 3.33 - These bits correspond the toggle gadgets on the Attributes requester. However, there are additional properties which can be controlled from RPL. These are listed below: IOF_SECTOR The sector angle which is a part of the geometry definition of all quadric primitives is enabled, and the object cross-section becomes a sector of an ellipse. IOF_SEGMENT The Sector Angle is used to define the chord of an ellipse and the object cross-section of the quadric primitive becomes a segment. Any RESERVED bits must be left as zero for future compatibility. 3.2.4 Tags The tags section consists of a list of pairs of tag values and tag ID's in that order. The list must terminate with "CEND", which because of the RPN nature of the RPL language must be entered first. For example, possible materials and methods associated with objects are described using tags. The method can be associated with the object by using the SMTH tag whose value is any method name. This can either be a user-defined method or one of the built-in methods. If no SMTH tag is present then NONE is used as default. Built in method names: NONE PATH ROTATION SWEEP SIZE STRETCH DIRECTION MOVE & DIR TRIM CURVES SIMPLE SKELETON SKELETON INV KINEMATIC MORPHING OPEN MORPHING CLOSED TRANSFORM WAVE RADIAL FORCE DIRECTED FORCE TANGENT FORCE COLLISION INT COLLISION FRICTION CREATION RPL Materials can be associated with objects using the tag SMAT with the material name. For example, "wood1" "SMAT". 3.2.5 Return Value All the creation words return the address of the primitive created. If an illegal geometry is defined then RPL will terminate execution and raise an error. - REFERENCE 3.34 - 3.2.6 Word Definitions WORD C_AIMPOINT TEMPLATE VPosition bR bG bB bA sName iAttr TagList C_AIMPOINT aObject WORD C_ATTRIB TEMPLATE iR, iG, iB, iA sName iAttr TagList C_ATTRIB aObject EXAMPLE ( create a texture with mapping type "Default" ) 255 255 255 0 ( RGBA ) "wood_texture" ( Name ) IOF_TEXTURE ( Attrib ) "CEND" ( Tags ) "wood" "SMAT" C_ATTRIB DROP WORD C_CONE TEMPLATE Vapex Va Vb Vaxis Vp Vm Vn [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CONE aObject EXAMPLE ( surface ) 1.50 1.50 2.00 (center) 0.50 0.00 0.00 ( a ) 0.00 0.50 0.00 ( b ) 0.00 0.00 -1.00 ( c ) ( bounding plane ) 1.50 1.50 1.00 ( p ) 0.00 0.50 0.00 ( m ) 0.50 0.00 0.00 ( n ) 255 255 255 0 ( RGBA ) "cone" ( name ) 0 ( attr ) "CEND" ( tags ) C_CONE DROP WORD C_COORDSYS TEMPLATE Vorigin Vx Vy Vz bR bG bB bA sName iAttr TagList C_COORDSYS aObject - REFERENCE 3.35 - WORD C_CUBE TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vdvect bR bG bB bA sName iAttr TagList C_CUBE aObject EXAMPLE ( create a cube animated by ) ( a RPL method MethodWord ) 2.00 3.01 0.00 ( first vertex ) 3.01 3.01 0.00 ( second vertex ) 2.00 2.00 0.00 ( third vertex ) 0.00 0.00 1.00 ( dvect ) 255 255 255 0 ( RGBA ) "cube" ( name ) 0 ( attr ) "CEND" "RPL" "SMTH" "MethodWord" "SRPL" ( See MTH_CREATE example ) C_CUBE DROP WORD C_CUTCONE TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CUTCONE aObject EXAMPLE ( create a sectored cut-cone ) ( surface ) -2.51 -0.50 2.50 (center) 0.50 0.00 0.00 ( a ) 0.00 0.50 0.00 ( b ) 0.00 0.00 -1.50 ( axis ) ( first bounding plane ) -2.51 -0.50 1.00 ( p1 ) 0.001 1.00 0.00 ( m1 ) 1.00 0.00 0.00 ( n1 ) ( second bounding plane ) -2.51 -0.50 2.00 ( p2 ) 0.00 1.00 0.00 ( m2 ) 1.00 0.00 0.00 ( n2 ) 0.00 4.71 ( angles ) 255 255 255 0 ( RGBA ) "cutcone" ( name ) IOF_SECTOR ( attr: sector ) "CEND" C_CUTCONE DROP WORD C_CUTPOLYMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vvertex3 Vvertex4 Vvertex5 [Vvertexn ..] iCount bR bG bB bA sName iAttr TagList C_CUTPOLYMID aObject - REFERENCE 3.36 - Note: iCount specifies the number of vertices on each polygonal face of the polymid, NOT the total number of vertices. There must be an equal number of vertices for both faces, or the geometry is illegal. WORD C_CUTPYRAMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vvertex3 Vvertex4 Vvertex5 bR bG bB bA sName iAttr TagList C_CUTPYRAMID aObject WORD C_CYLINDER TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_CYLINDER aObject WORD C_ELLIPSE TEMPLATE Vcentre Va Vb Vdvect [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_ELLIPSE aObject WORD C_ELLIPSEG TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iR iB iG iA sName iAttr TagList C_ELLIPSEG aObject - REFERENCE 3.37 - WORD C_ELLIPSOID TEMPLATE Vcentre Va Vb Vaxis bR bG bB bA sName iAttr TagList C_ELLIPSOID aObject WORD C_GROUP TEMPLATE iIndx0 [iIndxn ..] iCount bR bG bB bA sName iAttr TagList C_GROUP aObject OPERANDS iIndxn - Indexes of the points of the freeform. DESCRIPTION Creates a sub-group primitive referring to the points of a freeform. One tag in must be SOBJ and its value must contain the path and name of the freeform. EXAMPLE 0.0 0.0 0.0 0.0 0.1 0.0 1.0 1.0 0.2 3 ( count ) 3 ( type ) 0 ( geometry flags ) 255 255 255 0 ( RGBA ) "line" ( name ) IOF_RTINVISIBLE ( attr: ) "CEND" ( tags ) C_LINE DROP ( point references ) 0 2 2 ( count ) 255 255 255 0 ( RGBA ) "line_group" ( name ) 0 ( attr: ) "CEND" ( tags ) "/Root/line" "SOBJ" C_GROUP DROP SEE ALSO C_LINE C_MESH WORD C_HYPERBOL TEMPLATE Vcentre Va Vb Vaxis Vp1 Vm1 Vn1 Vp2 Vm2 Vn2 [fStAngle fEnAngle] iRiBiGiA sName iAttr TagList C_HYPERBOL aObject - REFERENCE 3.38 - WORD C_LEVEL TEMPLATE wBoolean sName iAttr TagList C_LEVEL aObject DESCRIPTION Creates a level with the attributes and tags supplied. The Boolean Operator type is specified by wBoolean as follows: wOT_AND wOT_OR Note: The level does not become the Current Level. EXAMPLE wOT_OR "mylevel" 0 "CEND" C_LEVEL DROP SEE ALSO: O_CURRENT WORD C_LINE TEMPLATE Vpt0 Vpt1 [Vptn ..] iCount wFreeType wGeomFIags bR bG bB bA sName iAttr TagList C_LINE aObject EXAMPLE ( points ) 1.00 -1.00 0.00 2.00 -1.00 0.00 2.00 -2.00 0.00 1.00 -2.00 0.00 4 ( count ) 3 ( type ) wGF CLOSEU ( geom. flags ) 255255 255 0 ( RGBA ) "mycurve" ( name ) 0 ( flags ) "CEND" C_LINE DROP Note: For B-spline lines there must be a minimum of four points. WORD C_LINK TEMPLATE sName iAttr TagList C_LINK aObject DESCRIPTION Create a symbolic link. One of the tags must be "SOBJ" and its value is the path and name for the object the link refers to. EXAMPLE "link" 0 "CEND" "/Root/rectangle" "SOBJ" C_ LINK - REFERENCE 3.39 - WORD C_MESH TEMPLATE Vpt[0,0] Vpt[0,1] [Vpt[u,v] ..] Vpt[1,0] Vpt[1,1] [Vpt[u,v] ..] iU iV wFreeType wGeomFIags bR bG bB bA sName iAttr TagList C_MESH aObject OPERANDS iU, iV - number of points for each dimension of the mesh. Note: For a B-spline mesh there must be at least four points for each dimension. The total number of points for the mesh must be the product of iU and iV. EXAMPLE ( line 0 ) -0.50 0.50 0.00 -0.17 0.50 0.00 0.17 0.50 0.00 0.50 0.50 0.00 ( line 1 ) -0.50 0.17 0.00 -0.17 0.17 0.00 0.17 0.17 0.00 0.50 0.17 0.00 ( line 2 ) -0.50 -0.17 0.00 -0.17 -0.17 0.00 0.17 -0.17 0.00 0.50 -0.17 0.00 ( line 3 ) -0.50 -0.50 0.00 -0.17 -0.50 0.00 0.17 -0.50 0.00 0.50 -0.50 0.00 4 ( width ) 4 ( height ) 3 ( type ) 0 ( geom. flags ) 255 255 255 0 ( RGBA ) "mesh" ( name ) 0 ( attr: ) "CEND" C_MESH DROP WORD C_OFFSET TEMPLATE Vposition bR bG bB bA sName iAttr TagList C_OFFSET aObject EXAMPLE ( create blue light-point that doesn't cast shadows ) 0.0 0.0 0.0 ( position ) 35 35 255 0 ( RGBA ) "BlueLight" ( name ) IOF_LIGHTSOURCE IOF_SHADOWLESS BOR "CEND" C_OFFSET DROP - REFERENCE 3.40 - WORD C_POLYGON TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vpt..] Vdvect iCount bR bG bB bA sName iAttr TagList C_POLYGON aObject WORD C_POLYHEDRON TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vvertexn ..] Vdvect iCount bR bG bB bA sName iAttr TagList C_POLYHEDRON aObject WORD C_POLYMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 [Vvertexn ..] Vapex iCount bR bG bB bA sName iAttr TagList C_POLYMI D aObject WORD C_PYRAMID TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vapex bR bG bB bA sName iAttr TagList C_PYRAMID aObject WORD C_RECTANGLE TEMPLATE Vvertex0 Vvertex1 Vvertex2 Vdvect bR bG bB bA sName iAttr TagList C_RECTANGLE aObject - REFERENCE 3.41 - WORD C_TRISET TEMPLATE Vpt0 Vpt1 Vpt2 [Vptn ..] iCount iIndx0 iIndx1 iIndx2 [iIndxn iIndxo iIndxp ..] iF aceCount wFreeType bR bG bB bA sName iAttr TagList C_TRISET aObject OPERANDS iIndxn - Indexes of the points forming the faces iFaceCount - Number of index triplets DESCRIPTION This word is used internally for creating a mesh with a triangular face topology. There are no menu functions for this. It is possible to create RPL programs to convert the data structures of other 3D graphics programs that use triangular mesh topologies into REAL 3D meshes using this word. Note: wFreeType must specify either polygonal or phong type WORD C_VIEWPOINT TEMPLATE Vleft Vright Vdvect bR bG bB bA sName iAttr TagList C_VIEWPOINT aObject OPERANDS Vleft - position of left view for stereo vision pair Vright - right view Vdvect - direction of stereo vision pair DESCRIPTION Create a viewpoint consisting of a stereo vision pair. 3.3 MODIFICATION WORDS RPL constants for these words can be found from the file "modify.rpl". This set of words in the RPL vocabulary allow object properties to be modified. Their target objects are specified by one or more addresses on the stack. This list is terminated with NULL. Each word requires additional information to carry out its function. This information is specified with a common integer operand, whose bits are defined as follows: - REFERENCE 3.42 - 3.3.1 Modify Flags FLAG DESCRIPTION IMF_ROTEXT Rotate & Extend if set IMF_NOSUB 0 - Modify sub-objects, 1 - Only modify targets IMF_NOCOG About COGs if set IMF_COGONLY With COGs if set IMF_BNDSIZE 0 - M_BEND Move, 1 - M_BEND Size IMF_PARABOL IMF_LINEAR IMF_SPHERE IMF_CURVE IMF_SIN All other bits are RESERVED and should be left as zero by the user for future compatibility. 3.3.2 Locking Object Data Before using any of the M words the data structure MUST be locked EXCLUSIVELY or conflict with other tasks may cause the system to crash. 3.3.3 Word Definitions WORD M_ALPHA TEMPLATE 0 aObject1 [...aObject] iA iFlags M_ALPHA OPERANDS iA - New alpha channel value for objects. DESCRIPTION Modifies so called "alpha channel" attribute of given objects. The value of iA must be between 0 and 255. EXAMPLE O_GETSEL ( objects ) 100 ( alpha ) 0 M_ALPHA WORD M_COLOR TEMPLATE 0 aObject1 [...aObject] iR iB iG iA iRegister iFlags M_COLOR OPERANDS iR iB iG iA - New color for objects iRegister - Register color for wire-frame - REFERENCE 3.43 - DESCRIPTION Changes the color of given objects. EXAMPLE 0 "/Root/rectangle" O FIND ( objects ) 255 255 255 0 ( RGBA ) 2 ( register ) 0 M_COLOR WORD M_COPY TEMPLATE 0 aObject1 [aObjectn ..] M_COPY DESCRIPTION Copies the targets to the Clip Buffer. EXAMPLE O_GETSEL ( objects ) M_COPY WORD M_CUT TEMPLATE 0 aObject1 [aObjectn ..] M_CUT DESCRIPTION Cuts targets from the hierarchy and places them in the Clip Buffer. EXAMPLE O_GETSEL ( objects ) M_CUT WORD M_DELETE TEMPLATE 0 aObject1 [aObjectn ..] M_DELETE DESCRIPTION Deletes targets from hierarchy. EXAMPLE O_GETSEL ( objects ) M_DELETE WORD M_DUPLICATE TEMPLATE 0 aObject1 [aObjectn ..] aLevel iFlags M_DUPLICATE DESCRIPTION Duplicates given objects and inserts them in to the given object aLevel. EXAMPLE O_GETSEL ( objects ) O_GETCURR ( to ) 0 ( flags ) M_DUPLICATE - REFERENCE 3.44 - WORD M_EXTEND TEMPLATE 0 aObject1 [aObjectn ..] vCentre vDirect fCoeff iFlIags M_EXTEND DESCRIPTION The targets are extended about Vcentre along the direction specified by Vdirect by the amount specified by fCoeff. EXAMPLE O_GETSEL ( objects ) 0.21 0.22 0 ( center ) 0.97 -0.25 0 ( direction ) -0.6 ( coefficient ) 0 ( flags ) M_EXTEND WORD M_MIRROR TEMPLATE 0 aObject1 [...aObjectn] vCentre iFlags M_MIRROR DESCRIPTION The targets are mirrored about a plane that passes through Vcentre, and in the direction specified by Vdirect. EXAMPLE O_GETSEL ( objects ) -0.03 0.78 0 ( center ) -0.58 -0.81 0 ( axis ) 0 ( flags ) M_MIRROR WORD M_MOVE TEMPLATE 0 aObject1 [...aObjectn] Vdelta iFlags M_MOVE OPERANDS Vdelta - vector defining direction and amount to move targets. EXAMPLE O_GETSEL ( objects ) 0.2 0.2 2 0 ( delta ) 0 ( flags ) M_MOVE WORD M_MOVECOG TEMPLATE 0 aObject1 [...aObjectn] vPosition iFlags M_MOVECOG OPERANDS vPosition - new position for targets' COGs. - REFERENCE 3.45 - EXAMPLE O_GETSEL ( objects ) -0.23 0.52 0 ( position ) 0 ( flags ) M_MOVECOG WORD M_NAME TEMPLATE 0 aObject1 [...aObjectn] sName iFlags M_NAME DESCRIPTION Renames ALL targets to the name specified by sName. EXAMPLE O_GETSEL ( objects ) "newname" ( name ) 0 ( flags ) M_NAME WORD M_PASTE TEMPLATE aLevel iFlags M_PASTE DESCRIPTION Pastes copies of the Clip Buffer into the object pointed by aLevel. EXAMPLE "/Root/rect*" O_FINDWLD M_CUT "/Root/Level" O_FIND 0 M_PASTE WORD M_ROTATE TEMPLATE 0 aObject1 [aObjectn...] vCenter vHor vVert vNorm iFlags M_ROTATE DESCRIPTION The targets are rotated and scaled to the coordinate system defined by vCenter, vHor , vVert and vNorm parameters. If the lenghts of vHor, vNorm and vVert vectors are 1, then the target objects are only rotated. For example, if the length of the vector vHor is 2, the the size of the objects is doubled in the d irection defined by vHor. The syntax of this word reflects the functions Modify/Linear/Rotate, Rot&Ext and Deform. EXAMPLE O_GETSEL ( objects ) -0.32 0.4 0 ( center ) 0.83 0.56 0 ( hor ) -0.56 0.83 0 ( vert ) 0 0 1 ( norm ) 0 ( flags ) M_ROTATE - REFERENCE 3.46 - WORD M_SIZE2D TEMPLATE 0 aObject1 [aObjectn . .] vCenter vHor vVert fHCoeff fVCoef iFlags M_SIZE3D DESCRIPTION Changes the size of the targets in two dimensions about the center defined by vCenter. The directions in which the object is stretched are defined by the parameters vHor and vVert. This word reflects the internal implementation of the Modify/Linear/Size 2D function. EXAMPLE O_GETSEL ( objects ) -0.68 0.82 0 ( center ) 1 0 0 ( hor ) 0 1 0 ( vert ) 0.44 0.44 ( hf,vf ) 0 ( flags ) M_SIZE2D WORD M_SHEAR TEMPLATE 0 aObject1 [aObjectn...] vCenter vNorm vDir fCoeff iFlags M_SHEAR DESCRIPTION The targets are sheared in the direction defined by vDir parameter. The longer the distance between a point and vCenter in the direction defined by vNorm, the more it is moved along the vDir axis. The coefficient defines how much the targets are sheared. EXAMPLE O_GETSEL ( objects ) 0.28 0.36 0 ( center ) -0.92 -0.38 0 ( normal ) 0.38 -0.92 0 ( dir ) -0.83 ( coeff ) 0 ( flags ) M_SHEAR WORD M_SIZE3D TEMPLATE 0 aObject1 [aObjectn ..] Vcentre fCoeff iFlags M_SIZE3D DESCRIPTION Alter the size of the targets about the centre specified by Vcentre in all dimensions by the amount specified by fCoeff. EXAMPLE O_GETSEL ( objects ) -0.67 0.78 0 ( center ) 1.4 ( coefficient ) 0 ( flags ) M_SIZE3D - REFERENCE 3.47 - WORD M_STRETCH TEMPLATE 0 aObject1 [aObjectn ..] vCentre vHor vVert vNorm vCoeff iFlags M_STRETCH DESCRIPTION Stretches objects in three dimensions. How much the object is stretched is defined independently in all three dimensions by the parameter vCoeff. For example, if the value of vCoeff is 0 1 0, then the size of object is doubled in the direction defined by vVert. EXAMPLE O_GETSEL ( objects ) 0 0.3 0 ( center ) 1 0 0 ( hor ) 0 1 0 ( vert ) 0 0 1 ( norm ) -0.02 -0.23 0 ( coeff ) 0 ( flags ) M_STRETCH WORD M_SWAP TEMPLATE iFlags M_SWAP DESCRIPTION Swaps the order of selected objects. This function corresponds the function Modify/Structure/Swap. EXAMPLE 0 ( flags ) M_SWAP 3.4 OBJECT WORDS These words are all for creating and manipulating object data structure in the hierarchy. 3.4.1 Return Value Excluding O_EVAL, O_DERIV and O_SCAN, possible return values are always addresses to the data structure the word relates to. If the word fails to execute because the operands are invalid, then it returns NULL. 3.4.2 Locking Data Structure THE OBJECT DATA STRUCTURE MUST BE LOCKED BEFORE ANY OF THE O_words IS USED. Failure to do so may cause RPL code to crash the system. Object data structure should be unlocked as early as possible, because locking prevents other tasks from accessing object data. If the user's RPL code only reads data structures, then shared access can be used. If the code modifies data (M_words, O_DELETE etc.), then exclusive access MUST be used. See: O_LOCK. - REFERENCE 3.48 - 3.4.3 Word Definitions WORD O_CREATAG - Create Object Tag TEMPLATE aObject TagList O_CREATAG aTagAddr DESCRIPTION Creates and adds to the given object the given tags. The tags are defineds as pairs of a Tag Value and a Tag ID, and the list must be terminated with "CEND". The word returns the address of the last Tag ID created. Note: The address of the Tag Field is the address of the Tag ID + 4. If the tag is an integer (lxxx) then the Tag Field is the Tag Value, otherwise it is the address of the Tag Values. EXAMPLE ( create vector tag to the object "/Root/myobj" ) "/Root/myobj" O_FIND "CEND" 12.0 5.0 0.0 "VMyT" O_CREATAG DROP WORD O_CURRENT TEMPLATE aObject O_CURRENT aPrevCurr DESCRIPTION This makes the object specified by aObject the current level. It returns the address of the previous current level unless the object is a primitive with no sub-structure ( e.g. an ellipsoid ). EXAMPLE "/Car/Engine" O_FIND O_CURRENT WORD O_DELETE TEMPLATE aObject O_DELETE DESCRIPTION deletes the object whose address is aObject. Note: That NULL is a valid address for O_DELETE, in which case the word does nothing. EXAMPLE "/Root/myobj" O_FIND O_DELETE WORD O_DERIV TEMPLATE aParam VPSpace O_DERIV Vdir - REFERENCE 3.49 - DESCRIPTION This returns the three floating-point values of the direction evaluated from the parameter aParam with the parameter values specified by VPSpace. The vector components of VPSpace correspond the r, s and t dimensions. Note: The operand aParam must point to an evaluable object or an error will follow. EXAMPLE ( get the address of a valid parameter ) "/Root/line" O_FIND ( specify the Parameter Space coordinates ) 0.5 0.0 0.0 O_DERIV F.F.F ( print out the direction ) WORD O_EVAL TEMPLATE aParam VPSpace O_EVAL Vpoint DESCRIPTION This returns the three floating-point values of the point evaluated from the parameter aParam with the parameter values specified by VPSpace. The vector components of VPSpace correspond to the r (Time), s and t dimensions. Note: The operand aParam must point to a valid parameter or an error will result. EXAMPLE ( get the address of a valid parameter ) "/Root/ellipse" O_FIND ( specify the Parameter Space coordinates ) 0.5 0.0 0.0 O_EVAL WORD O_FIND TEMPLATE sName O_FIND aObject DESCRIPTION Attempts to find an object by its name. If an object is found, its address is pushed onto the stack. If not found, NULL is returned. EXAMPLE : MyRename ( sNewName sOIdName ) O_FIND DUP IF bOFO_NAME + CPY ELSE DROP ENDIF ; "myrect" "/Root/Level/rectangle" MyRename WORD O_FINDTAG TEMPLATE aObject sTagID O_FNDTAG aTagAddr - REFERENCE 3.50 - DESCRIPTION Attempts to find the tag specified by sTagID from the object specified by the address aObject. It returns the address of the Tag ID if the tag is found. note: See O_CRETAG for Note: S about Tag ID, Tag Field and Tag Values. EXAMPLE : TagTest "/Root/Level" O_FIND "FMAS" O_FNDTAG IF "Yes" PUTS ELSE "FMAS not found" PUTS ENDIF ; WORD O_FINDWILD TEMPLATE sWild O_FINDWILD 0 aObject1 [aObjectn ..] DESCRIPTION Attempts to find objects whose name matches the given wild-card, and pushes the address for each match onto the stack. Zero is used for terminating this address list. The wild-card characters available are: * - any number of any characters ? - any single character . - current level .. - parent level / - level separator Note: The list of object addresses can be used directly by the M_words. EXAMPLE ( move all objects at the current level ) ( whose name ends with "le" ) "* le" O_FINDWILD 0.10 0 0 M_MOVE REFRESH WORD O_GETCUR TEMPLATE O_GETCUR aCurrent DESCRIPTION Returns the address of the current level. EXAMPLE ( pop up one level ) O_GETCUR O_GETPAR O_CURRENT WORD O_GETNEXT TEMPLATE aObject O_GETNEXT aNextObj DESCRIPTION Returns the address of the next object in the hierarchy at the same level as aObject, unless the object was the last in which case NULL is returned. - REFERENCE 3.51 - EXAMPLE : PrintLevel ( aLevel ) O_GETSUB BEGIN DUP WHILE DUP bOFO_NAME + PUTS O_GETNEXT REPEAT DROP ; ( print objects inside the current level ) O_GETCUR PrintLevel WORD O_GETPAR TEMPLATE aObject O_GETPAR aParent DESCRIPTION This returns the address of the of the parent of the object pointed by aObject unless there is no parent i.e. aObject is the Root level. Note: This works only if the object is linked to the object data structure. WORD O_GETPREV TEMPLATE aObject O_GETPREV aPrevObj DESCRIPTION This takes a pointer to an object as its operand, and returns a pointer to the previous object at the same hierarchy level. If there is no previous object, NULL is returned. Note: Due to the internal implementation, it is faster to fetch the address of the next object than the previous one. This word works only if the object is linked to the object data structure. WORD O_GETSEL TEMPLATE O_GETSEL 0 aObject1 [aOjectn ..] DESCRIPTION Returns a list of obJect addresses to the selected obJects. The list is terminated with zero. EXAMPLE ( move selected obJects ) O_GETSEL 0.1 1.0 0 0 M_MOVE REFRESH WORD O_GETSUB TEMPLATE aObJect O_GETSUB aFirstSub - REFERENCE 3.52 - DESCRIPTION This returns the address of the first sub-object of aObject unless it contains no sub-obJects, in which case 0 is returned. WORD O_LOCK TEMPLATE iAccess O_LOCK DESCRIPTION Locks or unlocks the obJect data structure (hierarchy) according to the value of iAccess as specified below: LOCK_REMOVE - Unlocks the obJect data LOCK_EXCLUSIVE - Tries to lock the data exclusively so that no other task can access it. If the data is already locked, the task in question goes to sleep. LOCK_SHARED - Tries to get shared access to the data structure. Several tasks can access the data structure if they all use shared access. For more details about locking and task access See: "Amiga ROM Kernel Reference Manual: Exec" EXAMPLE LOCK_EXCLUSIVE O_LOCK ( lock object data "/Root/re*" O_FIND O_DELETE ( delete object LOCK_REMOVE O_LOCK ( unlock ) SEE ALSO MAT_LOCK WORD O_PROP TEMPLATE aObject IProperty O_PROP .... PARAMETERS aObject - pointer to object IProperty - flags defining what properties the word should fetch: iOP_COG - Center of gravity iOP_ SIZE - Size of the object iOP_ DIR - direction iOP_MASS - the mass of the object. RETURNS The number of return values depends on the IProperty flags as follows: Property Return value iOP_COG A vector iOP_DIR Three vectors (coordinate system) defining the object space iOP_SIZE A float value defining the radius of the bounding sphere iOP_MASS A float value defining the mass of the object Parameters are pushed on the stack in this order. DESCRIPTION Takes the object and property flags and returns corresponding properties of the object on the stack. - REFERENCE 3.53 - EXAMPLE ( Print out the size of the current level O_GETCURR iOP_SIZE O_PROP F. ( Print out the size and the mass ( of the current level O_GETCURR iOP_MASS iOP_SIZE BOR O_PROP F.F. ( word printing the distance between ( given objects : PrintDist ( aObj1 aObj2 ) iOP_COG O_PROP ( COG of the 1st object 4 ROLL iOP_COG O_PROP ( COG of the 2nd obJect VSUB ( subtract COGs VLEN ( length of the vector F. ; WORD O_SCAN TEMPLATE aObject aCFA O_SCAN e DESCRIPTION Object scan and execute. This parses the hierarchical structure of the object pointed to by aObject and executes the RPL word pointed by aCFA for each sub-object. The RPL word executed receives the address of the current obJect as a parameter on the stack and must return a non-zero value to continue the scan or zero to stop. O_SCAN returns the value from the executed word. EXAMPLE : PrintName bOFO_NAME + PUTS ( print the name ) 1 ( return 1 to continue scanning ) ; "/Root" O_FIND & PrintName O_SCAN DROP WORD O_SELECT TEMPLATE 0 aObJect1 [aObJectn ..] O_SELECT DESCRIPTION Objects whose address is supplied as an operand become selected. Note: This word is useful for creating macros which select targets for menu function modifications. EXAMPLE ( find and select all rectangles ) ( at the current level ) "rectangle*" O_FINDWILD O_SELECT REFRESH - REFERENCE 3.54 - 3.5 ANIMATION WORDS WORD ASPEC TEMPLATE iFrameResol fStartTime sFileName iFlags sFormatString sScrName sFrameComm iCurrFrame iSamples fSeconds ASPEC DESCRIPTION Animation settings. The parameters of this word correspond the contents of the Animation window. iFlags parameter can contain the following bits: iAF_SAVE - save rendered frames iAF_WIRE - preview iAF_GOTO - go directly to given EndTime EXAMPLE 40 ( frame resolution ) 0 ( current time ) "ram:test" ( filename ) iAF_SAVE ( flags ) "%s%d" ( format ) "Real.1" ( screen name ) "" ( frame command ) 0 ( current frame ) 0 ( samples ) 1.0 ( seconds ) ASPEC 0 0 1.0 PLAY ( play the animation ) SEE ALSO PLAY WORD PLAY TEMPLATE aObject aMethod fEndTime PLAY PARAMETERS aObject, aMethod - Set these to NULL fEndTime - time value between 0 ... 1 DESCRIPTION Plays the animation to the given time using the current animation settings. If the given time is less than the current time, the animation is played backwards. Note: The first two parameters MUST be set to 0 for future compatibility. EXAMPLE : Forwars 0 0 1.0 PLAY ; : Backwards 0 0 0.0 PLAY ; : DoTwice Forwards Backwards ; DoTwice - REFERENCE 3.55 - WORD MTH_CREATE TEMPLATE aWord sName MTH_CREATE aMthAddr DESCRIPTION Creates a custom method to REAL 3D's Method list. The new method can then be assigned to objects as if it was one of the built-in methods. The a Word operand contains the address of the RPL word to be used by the method and sName specifies the name of the custom method as it will appear on the list. This can be up to 15 characters long; if a longer string is supplied, it will be truncated. The word returns the address of the method data. When an animation is played, this word is called with the following syntax: aNewTime aMthTime aMthObj aParentObj XXXXXXX where aNewTime - the address of the vector defining the new time. aMthTime - the address of the vector describing the current method time. If aNewTime is different than aMthTime, the method should "do something". aMthObj - the address of the object to which the method procedure was associated. aParObj - the address of the parent object of aMthObj. Also the following variables are defined during the animation: o1 - method object o2 - parent object t, u, v - new time fx, fy, fz - method's current time dt - time interval EXAMPLE : ColorProc 0 o2 @ ( address of object to be modified t 255 * ( R RANDOM 255 * ( G t 6.28*SIN 127 * 128 + ( B 0 ( A 2 ( register color 0 ( iFlags M_COLOR ; & ColorProc "Color" MTH_CREATE DROP WORD MTH_DELETE TEMPLATE aMthAddr MTH_DELETE DESCRIPTION Deletes the custom method specified by aMthAddr from the Method list. WORK MTH_FIND TEMPLATE sName MTH_FIND aMthAddr - REFERENCE 3.56 - DESCRIPTION Returns the address of the method given its name. Note: Do not use this word if you don't know the internal structure of the method. 3.6 I/O WORDS WORD FIL_LOAD TEMPLATE sFile iSections iReplace FIL_LOAD DESCRIPTION Loads the data sections specified by the bits of iSections from a REAL 3D Binary Format IFF file defined by the name sFile. The variable iReplace defines which sections replace the existing ones and which sections are inserted. The bits of iSections and iReplace select the Data Sections (REAL 3D IFF HUNKS) in the following way: HUNK DESCRIPTION RSCR Screens RWIN Windows RINF Measuring System RSTT Global Settings RGRI Grids RREN Render Settings RANI Animation Settings RATT Default Primitive Attributes ROBJ Objects RMTR Materials RCOL Named Colors RRPL RPL Text Note: The Version Hunk RVRS is always loaded. EXAMPLE "io.rpl" LOAD ( insert all sections found ) "MyProject" IRIO_ALL 0 FIL_LOAD ( insert all except objects ) "MyProject" IRIO_ALL IRIO_ROBJ FIL_LOAD WORD FIL_SAVE TEMPLATE sFile iSections iFlags FIL_SAVE DESCRIPTION Saves the data sections specified by the bits of iSections to the file specified in sFile using REAL 3D binary format. Note: See FIL_LOAD for the data sections bits and Note:s about iFlags. FIL_SAVE always saves the Version Hunk. - REFERENCE 3.57 - 3.7 MATERIAL WORDS WORD MAT_CREATE TEMPLATE sName wSpecularity wSpecBright wBrilliance wTransparancy wTurbidity wRefraction wCurlndex wEffect wRESERVED wRoughness wFlags wTurbSatur wMapMethods wRESERVED wFreqX wFreqY fSplineU fSplineV fSplineW fSplineH wRESERVED sImage bR bG bB bA wBumpHeight wDither wScopeHandle sScopeExpr fScope_a fScope_b wMapHandle sMapExpr fMap_a fMap_b wBumpHandle sBumpExpr fBump_a fBump_b wIndexHandle sIndexExpr fIndex_a fIndex_b TagList MAT_CREATE aMaterial OPERANDS wFlags The bits of this integer specify various material properties. wMTF_TRANCOL wMTF_UNSHADED wMTF_TILEX wMTF_TILEY wMTF_FLIPX wMTF_FLIPY wMTF_GRADEX wMTF_GRADEY wMTF_SPLINEMAP wMTF_SCOPEMASK wMTF_NOREFL wMTF_EXCL wMTF_SMOOTH wMapMethods The bits of this integer specify the mapping types: wMM_COLOR wMM_BUMP wMM_BRILL wMM_TRANSP wMM_CLIP wMM_SHADOW wMM_ENVIRONM DESCRIPTION Creates a material in the material library using the name specified with sName. It returns the address of the material created. WORD MAT_DELETE TEMPLATE aMaterial MAT_DELETE - REFERENCE 3.58 - DESCRIPTION Deletes the material pointed by aMaterial from the material library. WORD MAT_FIND TEMPLATE sName MAT_FIND aMaterial DESCRIPTION Searches the material specified by sName from the material library and returns its address, or zero if the search failed. WORD MAT_LOCK TEMPLATE iAccess MAT_LOCK DESCRIPTION Locks or unlocks the material data structure (material library) so that tasks can access it safely. Note: THE MATERIAL DATA STRUCTURE MUST BE LOCKED BEFORE ANY ACCESS FROM RPL CODE. Failure to do so may cause RPL code to crash the system. The material data structure should be unlocked as soon as possible, because locking prevents other tasks from accessing it. If the RPL code only reads materials then shared access can be used. If it changes materials, (MAT CREATE, MAT DELETE etc.), then exclusive access MUST be used. See: 4.4 O_LOCK for details of locking and iAccess. 3.8 MISCELLANEOUS WORDS WORD ERR_INSTALL TEMPLATE aErrHook ERR_INSTALL PARAMETERS aErrHook - address of the word to be called when an error occurs DESCRIPTION Installs a new error hook word to the RPL environment. When an error occurs the defined word is called. The number of possible hooks is not restricted in any way and they are called so that the hook installed first is called last. The called error hook word is removed by the system. This word is usually needed for error handling. If a RPL program allocates any system resources, it should also deallocate them when the program is terminated. Note: Error hooks cannot be nested. In other words, you cannot install error hook word for another error hook word. SEE ALSO ERR_REMOVE - REFERENCE 3.59 - EXAMPLE VARIABLE aMem : MyErrHook "All Right" "This is my own error handler" GET_KEY DROP aMem @ 512 MEM_FREE ; : DoSomething ( allocate some memory ) 512 0 MEM_ALLOC aMem ! ( install error hook ) & MyErrHook ERR_INSTALL ( then do something which causes error ) #@!)=? ( this is the normal exit procedure ) ( when everything went OK ) & MyErrHook ERR_REMOVE aMem @ 512 MEM_FREE ; DoSomething WORD ERR_REMOVE TEMPLATE aErrHook ERR_REMOVE PARAMETERS aErrHook - address of the RPL word installed with ERR_INSTALL DESCRIPTION Removes an error hook word from the RPL environment. If the given RPL word is not installed, an error message is produced. SEE ALSO ERR_INSTALL EXAMPLE : MyErrHandler ( .... ) ; & MyErrHandler ERR_INSTALL ( .... ) & MyErrHandler ERR_REMOVE WORD MEM_ALLOC TEMPLATE iSize iFlags ALLOC aAddr PARAMETERS iSize - the amount of memory to be allocated iFlags - must be 0 RETURNS aAddr - the addres of the allocated memory - REFERENCE 3.60 - DESCRIPTION Allocates given amount of memory from the system and returns the address of the allocated hunk. If allocation fails, 0 is returned. SEE ALSO MEM_FREE EXAMPLE VARIABLE aMyStr : AllocExample ( allocate 64 bytes of memory 64 0 MEM_ALLOC aMyStr ! aMyStr @ 63 "Enter any string" GET_STR IF aMyStr @ PUTS ENDIF aMyStr @ 64 MEM_FREE ; WORD MEM_FREE TEMPLATE aAddr iSize MEM_FREE PARAMETERS aAddr - the address of the memory to be freed iSize - the size of the memory to be freed DESCRIPTION Frees the memory allocated by MEM_ALLOC. SEE ALSO MEM_ALLOC WORD INHERIT TEMPLATE sName INHERIT DESCRIPTION The operand sName must be a valid RPL Environment (e.g. an existing RPL Window). The current RPL environment then inherits the vocabulary from this environment. When RPL looks for a word, the local vocabulary will be searched first, then any inherited definitions will be examined. INHERIT does not enable closed inheritance "loops". If an environment attempts to INHERIT from an environment that has already inherited the first one, then INHERIT will be ignored. There is one special RPL Environment called "Master" which is used for processing Macros and AREXX commands. This environment is created automatically by REAL 3D and does not have a window associated with it. EXAMPLE "RPL.1" INHERIT WORD MENU TEMPLATE iMenu iItem iSubItem MENU DESCRIPTION This word executes the menu function specified by the operands exactly as if it was selected using the mouse. Menus are numbered from zero starting from the top left. - REFERENCE 3.61 - Menu separators are counted as menu items. All three operands must be supplied even if there is no Sub-Menu. For a listing of the menu items and their three selection operands see the appendix B. EXAMPLE 2 2 1 MENU ( MODIFY/Properties/Name ) WORD REFRESH TEMPLATE REFRESH DESCRIPTION Refreshes all windows using their individual refresh settings. WORD RENDER TEMPLATE RENDER DESCRIPTION Renders all Views using their individual render settings WORD ROT_COORD TEMPLATE fxAngle fyAngle fzAngle aCoord ROT_COORD DESCRIPTION This rotates three vectors Vx, Vy, Vz in an array pointed by aCoord, around each other by the angles (in radians) specified by fxAngle, fyAngle & fzAngle. First Vy and Vz are rotated around Vx by fxAngle, then in the resulting system Vz and Vx are rotated around Vy by fyAngle etc. Note: Used extensively by the RPL Libraries. WORD SCR_SAVE TEMPLATE sScreen sFile SCR_SAVE I DESCRIPTION Saves the screen having the name sScreen to the file whose name is defined by sFile. It returns TRUE if the screen was found and saved, otherwise it returns FALSE. EXAMPLE "Real3D" "RAM:Real3D.IFF" SCR_SAVE WORD SYSTEM TEMPLATE sCLI SYSTEM DESCRIPTION This passes the string sCLI to the OS CLI for execution. - REFERENCE 3.62 - EXAMPLE "SYS:Tools/IconEdit" SYSTEM WORD WND_ADDR TEMPLATE sName WND_ADDR aWnd PARAMETERS sName - the name of any window RETURNS aWnd - the address of the window DESCRIPTION Returns the address of the window whose name is aName. If the window cannot be found, returns NULL. Note: Don't use this word if you don't know the internal structure of the window in question. WORD WND_OPEN TEMPLATE iType sName iLeft iTop Width iHeight WND_OPEN PARAMETERS iType - the type of the window to be opened. Can be one of the following: iWT_SELECT iWT_PROJECT iWT_PROJECTSB iWT_PROJECTBL iWT_SHELL iWT_TOOL iWT_ANIMCTRL iWT_COLCTRL iWT_PROJECTDB iWT_MATCTRL iWT_SCRCTRL sName - Name for the window. iLeft, iTop - Top left edge of the window wWidth, iHeight - Size of the window DESCRIPTION Opens a Real 3D window. EXAMPLE ( open the select window ) "editor.rpl" LOAD iWT_SELECT "MyWindow" 100 10 150 100 WND_OPEN WORD WND_SENDMSG TEMPLATE 0 aPn ... aP1 aWndName iMsglde WND_SENDMSG iMsgNum PARAMETERS 0 aPn ... aP1 - the addresses of parameters to be passed with the message aWndName - a string defining the target windows - REFERENCE 3.63 - iMsglde - a message identifier. Can be one of the following: iWM_ACTIVATE iWM_GETDATA iWM_INTUIMSG iWM_DIE RETURNS iMsgNum - a number of messages sent. DESCRIPTION Sends a message to given windows. The parameter list maximally consists of 5 addresses of parameters. An address 0 means that there are no more parameters to be passed. The purpose and amount of parameters depends on the message in question. The window name can include wildcards so that it is possible to send the message to more than one window. The return value indicates the number of messages sent. EXAMPLES Bring the palette window to the front and activate it: 0 "Color" WM_ACTIVATE WND_SENDMSG DROP Kill the "Color" window: 0 "Color" WM_DIE WND_SENDMSG DROP MyView window to front if exists. If not, create it: 0 "MyView" iWM_ACTIVATE WND_SENDMSG NOT IF iWT_VIEW "MyView" 10 10 300 200 WND_OPEN ENDIF WORD RAY_INTERS - Ray/surface intersection TEMPLATE aHandle avPos avDir avlnters avNorm RAY_PREP iResult PARAMETERS aHandle - a handle from the RAY_PREP word avPos - the address of a vector defining the position of the ray avDir - the address of a vector defining the direction of the ray avInters - the address of a vector to contain the intersection point avNorm - the address of a vector to contain the surface normal in the intersection point RETURNS iResult - TRUE if intersection was detected, FALSE if no intersection found. DESCRIPTION Executes an intersection test between a given obJect (aHandle) and a given ray (avPos and avDir). If no intersection was found, FALSE is pushed on the stack. Otherwise the variables avPos and avDir contain the position and the normal vector of the surface where the intersection between object and ray was detected. Note: This word can be used for creating "behavioral" animations where objects observe their living environment making decisions and conclusions depending on the information they receive. For example, a flying object can try to avoid hitting other objects a RPL method using this word. - REFERENCE 3.64 - EXAMPLE ( check if there is an object ) ( somewhere in front of us ) VVARIABLE vPos VVARIABLE vDir VVARIABLE vHit VVARIABLE vNrm VARIABLE iHnd 100 STRING sBuff : MyCollTest ( prepare intersection ) "/Root/Enemy" RAY_PREP iHnd ! ( shoot some rays ) 0 0 0 vPos V! ( start point of the ray ) 1 0 0 vDir V! ( direction of the 1 st ray ) iHnd vPos vDir vHit vNrm RAY_INTERS IF vHit V@ "Hit found in position %g %g %g" sBuff SPRINTF sBuff PUTS ENDIF 0 1 0 vDir V! ( direction of the 2nd ray ) iHnd vPos vDir vHit vNrm RAY_INTERS IF vHit v@ "Hit found in position %g %g %g" sBuff SPRINTF sBuff PUTS ENDIF ( free intersection handle ) iHnd @ RAY_FREE ; SEE ALSO RAY_PREP, RAY_FREE WORD RAY_FREE - Free a ray intersection handle TEMPLATE aHandle RAY_FREE PARAMETERS aHandle - pointer to a ray intersection handle DESCRIPTION Deallocates the data structures needed for ray intersection testing. EXAMPLE VARIABLE RayHandle "/Root/Tube" O_FIND RAY - PREP RayHandle ! .... RayHandle @+RAY_FREE SEE ALSO RAY_INTERS, RAY_PREP WORD RAY_PREP - prepare a ray/surface intersection handle TEMPLATE aObJect RAY_PREP aHandle PARAMETERS aObJect - a pointer to an object RETURNS aHandle - A ray intersection handle - REFERENCE 3.65 - DESCRIPTION Prepares data structures needed for ray intersection testing SEE ALSO RAY_INTERS, RAY_FREE WORD LIB_CALL TEMPLATE TagList iOffset iLibBase LIB_CALL OPERANDS TagList - Tag Values are addresses of operand data and Tag IDs are register names. e.g. "A0", "D0" etc. iOffset - Function offset in the library iLibBase - Library base-pointer DESCRIPTION Calls a library function using the given operands. The tag values are addresses so that RPL variables can be used to pass the operands for the library function, and return values are passed back through the same variables. EXAMPLE VARIABLE IntuiBase VARIABLE ScrOpernd 0 "intuition.library" LIB _OPEN IntuiBase ! 0 ScrOpernd ! "CEND" ( terminate tag list ) ( See Amiga ROM Kernel Ref: AutoDocs ) ScrOpernd "D0" 96 ( See Amiga ROM Kernel Ref: Exec ) IntuiBase @ ( Intuition lib. base pointer ) LIB_CALL ( call DisplayBeep(0) ) IntuiBase @ LIB_CLOSE WORD LIB_CLOSE TEMPLATE iLibBase LIB_CLOSE OPERANDS iLibBase - Library base-pointer DESCRIPTION Closes an OS library. Note: If iLibBase does not point to an open library when the word is called, system will crash. WORD LIB_OPEN TEMPLATE Version sName LIB_OPEN iLibBase OPERANDS iVersion - The version number of the library sName - The name of the library RETURNS iLibBase - The library base-pointer DESCRIPTION Attempts to open an OS library and returns the base-pointer if succeeds in opening, otherwise returns NULL. - REFERENCE 3.66 - 3.9 USER INTERFACE WORDS WORD BUSY_CANCEL TEMPLATE aHnd BUSY_CANCEL iBool PARAMETERS aHnd - a return value from the BUSY_OPEN word RETURNS iBool - TRUE or FALSE (1/0) DESCRIPTION Checks whether or not the user has pressed the CANCEL gadget of a given busy requester. If the gadget is pressed, TRUE is pushed on the stack, otherwise FALSE. SEE ALSO BUSY_OPEN, BUSY_CLOSE, BUSY_UPDATE EXAMPLE VARIABLE aBusyHnd : BusyTest 100 0 DO aBusyHnd @ "Rendering..." I BUSY_UPDATE ( Rendering ) aBusyHnd @ BUSY_CANCEL IF LEAVE ENDIF LOOP aBusyHnd @ BUSY_CLOSE ; WORD BUSY_CLOSE TEMPLATE aHnd BUSY_CLOSE PARAMETERS aHnd - a return value from the BUSY_ OPEN word DESCRIPTION Closes a given busy requester. SEE ALSO BUSY_OPEN, BUSY_UPDATE, BUSY_CANCEL EXAMPLE aBusyHnd @ BUSY_CLOSE WORD BUSY_OPEN TEMPLATE sHeader BUSY_OPEN aHnd PARAMETERS sHeader - title string RETURN aHnd - address of the busy requester. - REFERENCE 3.67 - DESCRIPTION Opens a busy requester with the given header text and returns a handle which can be used for updating the busy requester and checking whether the user has requested cancelling. SEE ALSO BUSY_CANCEL, BUSY_CLOSE, BUSY_UPDATE EXAMPLE VARIABLE aHnd : MyAnimation "Rendering Animation..." BUSY_OPEN aHnd ! 100 0 DO O_GETSEL 0.1 0 0 0 M_MOVE REFRESH aHnd @ 0 I BUSY_UPDATE LOOP aHnd @ BUSY_CLOSE ; WORD BUSY_UPDATE TEMPLATE aHnd aNewHdr iPer BUSY_UPDATE PARAMETERS aHnd - a return value from the BUSY_OPEN word NewHdr - a new a header text for the requester iPer - value between 0 and 100. DESCRIPTION Updates the contents of the busy requester. If the aNewHdr parameter is not 0, then it is assumed to be the address of the new header text for the requester. If it is NULL, the header text of the requester is not changed. The iPer parameter must be between 0 and 100. SEE ALSO BUSY_OPEN, BUSY_CLOSE, BUSY_CANCEL EXAMPLE VARIABLE aBusyHnd : BusyTest "Optimizing ..." BUSY_OPEN aBusyHnd ! 100 0 aBusyHnd @+0 I BUSY_UPDATE ( Optimizing ) LOOP 100 0 DO aBusyHnd @ "Rendering..." I BUSY_UPDATE ( Rendering ) LOOP aBusyHnd @ BUSY_CLOSE ; WORD GET_KEY TEMPLATE aGadTxts aHdrTxt GET_KEY iRetVal PARAMETERS aGadTxts - string defining gadgets to be created. Gadget texts are separated by the character "I". aHdrTxt - Headline string for the requester. RETURN - REFERENCE 3.68 - iRetVal - integer corresponding the selected gadget. The value corresponding the first (leftmost) gadget is 1 and the return value corresponding the rightmost gadget is 0 (cancel/negative choice should always be the rightmost one as suggested by the Amiga Style Guide). Intermediate gadgets/return values are incremented by one from left to right. DESCRIPTION Opens a requester with a given header text and gadgets, waiting the user to select one of them. The function returns a value corresponding the selected gadget. EXAMPLE "FIRSTlSECONDlTHIRDlCANCEL" "Select One of These" GET_KEY. WORD GET_FLT TEMPLATE aFIt aHdr GET_FLT iRetVal PARAMETERS aFIt - pointer to a floating point aHdr - headline text string for the requester RETURN iRetVal - TRUE of FALSE depending on the user's action EXAMPLE Opens a requester allowing the user to define a floating point value. Formula evaluation is supported. EXAMPLE ( define float variable ) FVARIABLE MyFIt : MyTest 3.14 MyFlt F! MyFlt "Define Angle" GET_FLT IF MyFlt F@ F. ENDIF ; MyTest WORD GET_STR TEMPLATE aStr iLen aHdr GET_STR iRet PARAMETERS aStr - a pointer to a buffer iLen - the maximum lenght of the string (lenght of the buffer - 1 ) aHdr - a header text for the requester RETURN iRet - 1 or 0 depending on the user's choice. DESCRIPTION Opens a requester allowing the user to define a string. - REFERENCE 3.69 - EXAMPLE ( create an object with custom name ) "creation.rpl" LOAD 16 STRING ObjNam : MyTest "Noname" ObjNam CPY ObjNam 16 "Create Object" GET_STR IF wOT_OR ObjNam 0 "CEND" C_LEVEL DROP ENDIF ; WORD GET_VECT TEMPLATE aVct aHdr GET_VECT iRet PARAMETER aVct - pointer to a vector (an array of 3 floating points) aHdr - a header text for the requester RETURN iRet - TRUE or FALSE depending on the user's choice. DESCRIPTION Opens a requester allowing the user to define three floating point values, in other words a 3D vector. Formula evaluation is supported. EXAMPLE ( move selected objects ) "vectors.rpl" LOAD VVARIABLE vDelta : MyTest 0.0 1.0 3.1 vDelta V! vDelta "Move Selected Objects" GET_VECT IF O_GETSEL vDelta F@ 0 M_MOVE ENDIF ; WORD GET_FILE TEMPLATE iType aNam aDir aHdr GET_FILE iRet PARAMETER iType - One of the follwing action qualifiers: iIO_READ - Selection is used for reading iIO_WRITE - Selection is used for writing iIO_DIR - Selection is used for defining a path aNam - pointer to an initial file name/result string aDir - pointer to an initial directory path aHdr - a header text for the requester RETURN iRet - TRUE or FALSE depending on the user's choice. - REFERENCE 3.70 - DESCRIPTION Opens a file requester on a given DOS drawer (directory) allowing the user to select a file name. If the user moves in the hierarchy, the contents of the buffer pointed by "iDir" is updated accordingly. If the user selects OK, the buffer pointed by "iNam" will contain the complete file name (including the path). Note: That both buffers should be large enough to hold the result strings. EXAMPLE ( load a Real 3D IFF file ) "io.rpl" LOAD 256 STRING Name 256 STRING Path : MyLoad "myfile" Name CPY "r3d2:projects" Path CPY iIO_READ Name Path "Load something" GET_FILE IF ( replace all sections: ) Name IIO_RALL IIO_RALL FIL_LOAD ENDIF ; MyLoad 3.10 WORDS WORD RX TEMPLATE sPrg RX PARAMETER sPrg - string defining the arexx program to be executed DESCRIPTION This word sends a given ARexx program to the ARexx manager process as if it was typed in from an Amiga DOS shell using the rx command. Note: That if the RX word does not return 0, it is not automatically interpreted as an error situation. The reason for this is that some applications use the return value for indicating something else than an error. EXAMPLE "ADDRESS COMMAND dir" RX "RENDER" RX SEE ALSO RX_RC WORD RX_RC TEMPLATE RX_RC - aRetVal RETURNS aRetVal - The address of the return value DESCRIPTION This word can be used for fetching the return value from a previously executed RX word. RX_RC returns the address of an integer variable containing the result. - REFERENCE 3.71 - EXAMPLE ( send ARexx command ) "ADDRESS STANDALONE RENDER" RX RX_RC @ ( fetch return value ) IF ( terminate the RPL program ) "ERROR:Cannot Execute" ERROR ENDIF Note: Although the word returns the address of the return value, currently it does not make sense to assign a return value to ARexx commands arriving to Real 3D's ARexx port. WORD RX_RESULT TEMPLATE RX_RESULT - aResStr RETURNS aResStr - Address of the result string DESCRIPTION This word can be used for accessing the result string variable of Real 3D. The word returns the address of the result string. RPL programs can read this variable after each sent ARexx message in order to detect the possible result strings returned by external applications. The word can also be used for passing a result string to an external application who have sent an ARexx message to the ARexx port of Real 3D. Note: That a result string is returned only if it is requested by the command sender application. Furthermore, all commands do not return a result string even if it is requested. If the ARexx command sent to Real 3D fails, result string is NOT returned. In other words, the result string is valid only if the return code indicates that no error occurred during command processing. EXAMPLE .... "RX ( send ARexx command ) RX_RC @ ( fetch return value ) IF "ERROR:Cannot Execute" ERROR ENDIF RX_RESULT PUTS ( process result string ) WORD RX_SETCLIP TEMPLATE sName sValue RX_SETCLIP PARAMETERS sName - Address of the name string sValue - Address of the value string DESCRIPTION This word can be used for putting new items to the Clip List or updating existing ones. Each item in the Clip List consists of a pair of strings defining a name and a value for the item. The Clip List can be used for passing information between Real 3D and ARexx and is typically used whenver two or more result strings are needed. EXAMPLE "rad" "0.5" RX_SETCLIP "position", "0.5, 0.8, 0.0" RX_SETCLIP - REFERENCE 3.72 - 3.11 VECTOR OPERATIONS These words are defined in the file "vectors.rpl". WORD VVARIABLE TEMPLATE VVARIABLE name DESCRIPTION Defines a vector variable. The name of the variable must follow the word VVARIABLE. The variable is initialized as 0 0 0. A vector variable is an array of three floating point variables. When the variable is later referenced by entering its name, the address of the first floating point is pushed onto the stack. EXAMPLE VVARIABLE myVector SEE ALSO v@ V! WORD V! TEMPLATE fX fY fZ aVariable V! PARAMETERS fX fY fZ - three values defining a vector aVariable - an address of the vector variable DESCRIPTION Store a vector in a variable. EXAMPLE VVARIABLE myVar 0 0 1.5 myVar V! WORD v@ TEMPLATE aVariable v@ fX fY fZ PARAMETERS aVariable - the address of a vector variable RETURNS fX fY fZ - contents of the variable DESCRIPTION Fetch a vector from a given address. EXAMPLE ( print the value of vMyVar ) vMyVar F@ V. WORD VADD TEMPLATE v1 v2 VADD vRes PARAMETERS v1 v2 - two vectors to be added RETURNS vRes - result vector - REFERENCE 3.73 - DESCRIPTION Vector addition. Pulls two vectors off the stack and pushes the result vector back. EXAMPLE VVARIABLE v1 VVARIABLE v2 VVARIABLE vRes 1 0 0 v1 V! ( v1 = 1 0 0 ) 0 1 0 v2 V! ( v2 = 0 1 0 ) v1 V@ v2 V@ VADD vRes V! ( vRes = v1 + v2 ) WORD VSUB TEMPLATE v1 v2 VSUB vRes PARAMETERS v1 , v2 - vectors to be subtracted RESULT vRes - result DESCRIPTION Pulls two vectors off the stack, subtracts them and pushes the result back onto the stack. EXAMPLE 10 5.0 0.5 ( v1 ) 5 5.0 0.5 ( v2 ) VSUB V. WORD VMUL TEMPLATE v f VMUL vRes PARAMETERS v - a vector to be multiplied f - a scalar value RESULT vRes = v1 * f DESCRIPTION Multiplies a vector by a scalar. In other words, each component of the given vector "v" is multiplied by the given float "f" and the result is pushed onto the stack. EXAMPLE ( duplicate the length of a vector ) 1.5 3.1 8.2 2.0 VMUL V. WORD VDOT TEMPLATE v1 v2 VDOT fRes PARAMETERS v1, v2 - two vectors to be operated RESULT fRes - Dot product of given vectors - REFERENCE 3.74 - DESCRIPTION Pulls two vectors off the stack, executes dot product and pushes the result (a floating point value) back onto the stack. EXAMPLE ( dot product of perpendicular vectors = 0 ) 1 0 0 0 1 0 VDOT F. WORD VCROS TEMPLATE v1 v2 VCROS vRes PARAMETERS v1, v2 - two vectors RESULT vRes - result vector DESCRIPTION Cross product. The result vector is always perpendicular to the operands v1 and v2. EXAMPLE 1 0 0 0 1 0 VCROS V. ( result = 0 0 1 ) WORD VNORM TEMPLATE v VNORM vRes PARAMETERS v - vector to be normalized RESULT vRes - unit vector DESCRIPTION Vector normalization. The given vector is divided by its length and the result is pushed back on to the stack. The lenght of the result vector is always 1. EXAMPLE 120.2 10.2 -2.1 VNORM WORD VLEN TEMPLATE v VCROS fLen PARAMETERS v - any vector RESULT fLen - the length of "v" DESCRIPTION Pulls the given vector off the stack and puts the length of it back to the stack. EXAMPLE 10 20 30 VLEN F. - REFERENCE 3.75 - WORD V. TEMPLATE v V. PARAMETERS v - vector DESCRIPTION Pulls a vector ( three float values ) off the stack and prints them out. WORD VCONSTANT TEMPLATE VCONSTANT name DESCRIPTION Defines a vector constant. EXAMPLE ( some useful constants ) 1 0 0 VCONSTANT vX 0 1 0 VCONSTANT vY 0 0 1 VCONSTANT vZ vX V. - REFERENCE 3.76 - Chapter 4 GEOMETRIC OBJECT PROPERTIES ------------------------------------- 4.1 GEOMETRIC PROPERTIES 4.1.1 Surface Definition The vectors and points of the data structure of each visible describe the mathematical surfaces that form the basis for the final visible surfaces that are produced by rendering. The surface definition can be modified by the various modification functions and boolean operations. How the data structure describes each surface of a visible is given in the following figures and text. 4.1.2 COG The center of gravity of each primitive occupies one vector. The tag MCOG can be used for overriding the default value. 4.1.3 Direction This property is defined by two vectors perpendicular to each other. The tags DDIR and DDIV can be used to redefine the defaults. The property describes the local obJect space coordinate system. 4.1.4 Size One floating-point value is used to define the size of each object. This represents the radius of a spherical volume that can contain the entire object. For a level, this bounding sphere encloses its sub-obJects. The default can be overridden with the FSIZ tag. For more information about tags see the reference chapter 5. 4.2 DEFAULT GEOMETRIC PROPERTIES The following text and diagrams describe the default geometric properties for each primitive and how the data structure relates to the surface definition. All the calculations shown involve vector arithmetic, and the following symbols are used: ASC - Absolute Spatial Coordinate ptn - Point on a line pt[u,v] - Point from a mesh vn - Vertex of a geometric solid The other symbols relate to the data structure of the primitive. PRIMITIVE : aimpoint, offset COG : position DIR : ASC z DIV : ASC x Figure r4-1: (PICTURE: R4-1) PRIMITIVE : cone COG: 0.3*center + 0.7*(intersection of the axis and the bounding plane) DIR : axis DIV : a PRIMITIVE : coordsys COG : origin DIR : z DIV : x - REFERENCE 4.1 - Figure r4-2: (PICTURE: R4-2) PRIMITIVE : cube COG : average of vertices DIR : dvect DIV : v1 - v0 Figure r4-3: (PICTURE: R4-3) PRIMITIVE : cut-cone, cylinder, ellipse-segment, hyperboloid COG : average of p1 & p2 DIR : axis DIV : a Figure r4-4: (PICTURE: R4-4) PRIMITIVE : cut-polymid COG : average of vertices DIR : vector between polygonal surface centers DIV : v1 - v0 Figure r4-5: (PICTURE: R4-5) PRIMITIVE : cut-pyramid COG : average of vertices DIR : vector between the rectangular surface centers DIV : v1 - v0 - REFERENCE 4.2 - Figure r4-6: (PICTURE: R4-6) PRIMITIVE : ellipse COG : center DIR : dvect DIV : a Figure r4-7: (PICTURE: R4-7) PRIMITIVE : ellipsoid COG : center DIR : axis DIV : a PRIMITIVE : group COG : average of indexed points DIR : vector between 1 st & 2nd indexed points DIV : ILL-DEFINED PRIMITIVE : level COG : average of all sub-obJect COGs unless empty DIR : DIR of 1 st sub-obJect unless empty DIV : DIV .. .. .. .. .. .. Figure r4-8: (PICTURE: R4-8) PRIMITIVE : line COG : pt0 DIR : pt1 - pt0 DIV : ILL-DEFINED PRIMITIVE : link COG : fetched from target DIR : .. .. .. DIV : .. .. .. Figure r4-9: (PICTURE: R4-9) PRIMITIVE : mesh COG : average of all points DIR : (pt[1 ,0] - pt[0,0]) x (pt[0, 1] - pt[0,0]) DIV : pt[1 ,0] - pt[0,0] Note : x - vector cross product - REFERENCE 4.3 - Figure r4-10: (PICTURE: R4-10) PRIMITIVE : polygon COG : average of vertices DIR : dvect DIV : v1 - v0 Figure r4-11: (PICTURE: R4-11) PRIMITIVE : polyhedron COG : aver age of vertices DIR : dvect DIV : v1 - v0 Figure r4-12: (PICTURE: R4-12) PRIMITIVE : polymid COG : average of vertices and apex DIR : vector between base-center and apex DIV : v1 - v0 Figure r4-13: (PICTURE: R4-13) PRIMITIVE : pyramid COG : 0.3*apex + 0.7*base-center DIR : vector between base-center and apex DIV : v1 - v0 - REFERENCE 4.4 - Figure r4-14: (PICTURE: R4-14) PRIMITIVE : rectangle COG : average of vertices DIR : dvect DIV : v1 - v0 PRIMITIVE : triset COG : average of all points DIR : direction of 1 st face DIV : direction of 2nd face Figure r4-15: (PICTURE: R4-15) PRIMITIVE : viewpoint COG : average of left & right DIR : dvect (initialized to the direction of the current aimpoint) DIV : right - left - REFERENCE 4.5 - Chapter 5 TAGS -------------- TAGs are used for expanding the object and the material data structures. They contain alternatives to assumed default values or additional information to describe some additional property for the object. These additional properties are often needed when creating new animation techniques (methods) and procedural materials. Internally a tag consists of two parts: the tag ID (tag identifier), and the tag field, which points to the actual tag values unless it is an integer (lxxx) tag, in which case the tag field is the actual tag value. From the user perspective, a tag consists of the tag ID and the tag value, unless RPL is being used; then it is necessary to access the tag values via the tag field. The user can utilize his/her own tags by creating a function that looks for a particular tag ID and then acts upon or modifies its values. This function takes the form of an RPL word definition which is then invoked either by executing it directly, executing it via the user interface (a macro or a tool icon), or by attaching it to a method as a method procedure. Tags provide the final degree of customization necessary to expand the features of REAL 3D For example: IAGE 32 SNAM John Houston FLEN 182.5 VPOS 1.5 1.2 0.5 5.1 Tag identifiers The tag ID consists of four ASCII characters and its structure is generally Txxx, where: - T describes the type of the tag value - xxx is the identifier used for recognizing individual tags. There are two basic kinds of tags: 1. Tags affected by Real 3D modify functions. When user modifies the object to which the tag is attached, the tag value is modified as well. There are two sub-classes of modifiable tags: "M" and "D". 2. Tags which are not affected by the modify functions. Tag type characters can be one of the following: C - Control tag, used only internally. F - Floating-point tag. The tag field is a pointer to an actual floating-point tag value. I - Integer tag, the tag field is used directly to store the value. S - String tag, the tag field points to a string which is the tag value. V - Vector tag, the tag field is a pointer to an array of three floating-points. M - Modifiable vector tag. Modified as absolute 3D point by REAL 3D modify functions. D - Modifiable vector tag. Modified as a vector, so modify functions such as rotate and mirror affects this tag, but the move function has no effect at all. - REFERENCE 5.1 - 5.2 Reserved tag identifiers The following are the tag ID's reserved for use internally by REAL 3D: CEND - This ends the tag data structure. It does not appear on the tag requesters. DDIR - Primary direction vector for object. For example: "DDIR 1.0 0.0 0.0" DDIV - Secondary direction vector for object. For example: "DDIV 0.0 -1.0 0.0" DDIR defines obJect "axis" and DDIV defines how object is rotated around this axis. These tags are used where exactly defined direction for objects is needed and they override the default object direction. These tags do not have to be defined as perpendicular to each other as they are "normalized" internally so that DDIV is always perpendicular to DDIR. MCOG - Center of Gravity. This tag can be used for overriding the default center of gravity. For example: "MGOG 1.0 1.0 0.5" SCRE - Formula producing logical result to control target creation by CREATION method; the result should be assigned to the "I" variable. For example: "l=(t> 1 .0)" SDEL - Logical formula to control target deletion by CREATION method. For example: "l=(y> 1.0)" SMAT - This tag is used for defining materials associated with objects. All mapping primitives contain this tag. The tag value contains the name of the material. For example: "SMAT wood1". Note: That if the name of any material is changed, then the tag value for SMAT should also be changed to reflect the new material name. SMTH - The name of the method associated with object. For example: "SMTH SIMPLE SKELETON". SOBJ - Reference to another obJect. Links and groups refer to other objects and the information about the target object is stored using this tag. The tag value contains the full name of the target object including the path (for example: /Root/myobj/mesh). The path can be absolute or relative. SRPL - The contents of this tag can be any RPL program. The purpose of it depends on the obJect it is attached to. When associated with method or parameter object, the tag can be used for customizing built-in methods and evaluable parameter objects (see SFOR). The tag is also used for attaching RPL procedures to objects allowing user to create intelligent "thinking" objects. For example: "SRPL MyMethod". VFRQ - How much faster (or slower) a method's time runs compared to its parent time. For example "VFRQ 3.0 0.0 0.0". VOFF - Offset vector used by methods. For example "VOFF 0.5 0.5 0.5". VPHS - General usage phase tag. The tag can be used for modifying a method's local time. When associated with target objects, the purpose of the tag depends on the method in question. For example "VPHS 0.2 0 0". VTIE - Time end tag. When the time reaches this value, the method stops. For example: "VTIE 0.8". VTIM - This tag is used for defining a method's current time, i.e. the time that the method's current state corresponds to. For example: "VTIM 0.5". - REFERENCE 5.2 - VTIS - Used for defining a sub-range from parent time. When the current time reaches this value, the method is activated. For example: "VTIS 0.1". FFRI - Surface friction between particles involved in collisions. This causes changes to velocity and spin. For example: "FFRI 0.5". FMAS - Mass for obJect. If this tag is absent the default mass for the object is 100.0 kg. For example: "FMAS 10000.0". FREB - Rebound energy for collision detection system. With this tag it is possible to specify the "elasticity" of collisions with the object having this tag. The default value is 1.0 (fully elastic); the value 0 results to fully non-elastic behaviour. For example: "FREB 0.8". FSIZ - Size for particle. This tag can be used for overriding the default object size. The collision detection system uses the size property to define when distance between objects is small enough for surface collision detection. The size is also needed by the FRICTION method (the bigger the object, the higher the friction force). For example: "FSIZ 2.3". ICSM - Collision sampling accuracy used by COLLISION and INT COLLISION methods. The default value 0 gives normal accuracy, the other possible values 1 and 2 give increased accuracy. For example: "ICSM 1". SFOR - String tag used for defining formulas. The contents of this tag is always evaluated when associated with method and parameter objects. Some methods also allow this tag to be associated with target objects. For example: "SFOR if(x<0, f=f*2, f=0)". VSPI - Spin for particle methods. Value defines angular velocity around direction axes in radians. The tag value can also be negative to reverse the direction of rotation. For example: "VSPI 3.14 6.28 -0.5". VVEL - Velocity of particles used by particle methods. For example: "VVEL 10.0 5.0 0.0". SIDE - Unique identifier used for linking group and link primitives with their targets. If the object referred by a SOBJ tag cannot be found, then the target is resolved using this tag. SWND - Window name. Can be added to viewpoint and aimpoint primitives to identify the window whose camera orientation they specify. - REFERENCE 5.3 - Chapter 6 AREXX INTERFACE OF REAL 3D ------------------------------------ 6.1 General ARexx is undoubtedly one of those things which make the Amiga platform something special. ARexx provides applications with a common communication protocol, this kind of versatility is difficult to find on other platforms. ARexx has quickly become a standard supported almost by all commercial products and REAL 3D is not an exception. Basically REAL 3D contains a so called "active" ARexx port, similar to many other programs. In other words, REAL 3D can send and receive ARexx commands. However, the way how the ARexx interface of REAL 3D is implemented, is somewhat unique. In REAL 3D there is no fixed set of supported ARexx commands. Instead, commands arriving at REAL 3D are passed directly to the parser of REAL 3D'S built in programming language - RPL. 6.2 ARexx vs. RPL REAL 3D uses RPL extensively. For example, it is used as a macro recording language, as a scene description method, procedural textures and animations are described using it, key and icon bindings are defined using RPL, user defined custom formulas describing mathematical textures are evaluated using RPL etc. Because of the time critical nature of some of these tasks, RPL was designed to be fast in its execution. This led to quite a low level "compiled" language. ARexx is based on the REXX programming language and is an "interpreted" language. Because of this, it is slower in its execution and cannot be used for implementing time critical tasks like procedural textures. However, the strongest point of ARexx is that it can be used for integrating different applications with each other. It is important to realize that RPL and ARexx are not two different "competitive" programming language implementations for REAL 3D. ARexx interface of REAL 3D is more than just set of ARexx commands; it is actually another programming language. Together, ARexx and RPL provide the user with a great deal of power and flexibility due to the fact that both ARexx and RPL are "interactive" languages, they fit perfectly together. This kind of ARexx interface has many advantages. One of the biggest is that the interface is not fixed; the user can expand it simply by programming new RPL words. In other words, the ARexx interface of REAL 3D is not "hard coded" to the program. Another advantage is that you can use RPL for those tasks that better suit RPL and ARexx for those tasks where ARexx appears to be a more natural choice. Thanks to the clever implementation of ARexx, you can mix RPL and ARexx programs without any problems. You don't have to know much about RPL in order to use the ARexx interface of REAL 3D. You can call existing RPL words as if they were commands implemented Just for the ARexx interface. However, no programming language contains all possible functions for all possible tasks. There are always cases where some new useful functions could help and speed up the Job. Therefore, a system where the ARexx interface is not fixed and can be quickly extended can turn out to be an extremely valuable feature. We could say that all the power provided by RPL can also be achieved through ARexx programs and vice versa. The interface is established using a set of RPL words which can be used for sending ARexx commands to other applications, for passing results back to them, accessing the ARexx Clip List and so on. In the following sections we will show you how to use the ARexx interface of REAL 3D. However, this chapter is not ment to be a tutorial for ARexx programming or the RPL programming language. For more information about the ARexx programming, see your Amiga system software manuals. - REFERENCE 6.1 - 6.3 Sending ARexx Commands to the ARexx Port of REAL 3D The name of the REAL 3D ARexx port is REAL3D0. If there are more than one REAL 3Ds running simultaneously, the postfix index is incremented by one for each new instance so that it remains unique and can be used for identifying all program instances if needed. rx "ADDRESS REAL3D0 RENDER" When entered in an AmigaDOS shell window, this command line sends a RENDER command to REAL 3D which causes REAL 3D to render all its windows. A more common way to send ARexx commands to REAL 3D is to write an ARexx program and save it to a file. This ARexx program can then be invoked from the AmigaDOS shell or any application which supports ARexx. For example, the following ARexx program can be saved as "ram:test.rexx" and executed by entering the command "rx ram:test". /* Render REAL 3D windows */ ADDRESS REAL3D0 RENDER You can execute any REAL 3D menu function by using the MENU command. As the RPL word descriptions specify, the RPL word MENU takes three parameters where the first defines the menu title, the second defines menu item and the last defines the submenu. /* Activate the function Modify/Structure/Name */ ADDRESS REAL3D0 2 2 0 MENU The MENU command allows you to execute REAL 3D functions using the highest level interface. For example, the command: /* play forwards */ ADDRESS REAL3D0 4 1 0 MENU plays the animation to the end. However, if you don't want to access functions at the highest level, you have to consult the RPL reference chapter in order to find how to access the desired function at a lower level. F or example, if you want to ask REAL 3D to load the object file "r3d2:objects/myobj", you don't want to use the highest level access to the ProJect/Objects/Load function (because it opens the file requester asking the user to select the file name). In this case the word FIL_LOAD can be used instead. /* ask Real to load file r3d2:objects/myobj" */ ADDRESS REAL3D0 "r3d2:objects/myobj" lIO_RALL 0 FIL_LOAD If you want to invoke the function Animate/Control/Goto so that REAL 3D asks the user to define the moment in time where to play, you can use MENU word. Another possibility is to use lower level access and use the PLAY word. PLAY takes one parameter which defines the moment in time to which the animation should be played: /* play animation to half way */ ADDRESS REAL3D0 0.5 PLAY For more information about all possible RPL words (REAL 3D ARexx commands), see the RPL reference chapter. Because all arriving ARexx commands are passed directly to the RPL parser, it is possible to mix ARexx and RPL freely. For example, the following ARexx program produces a simple animation. /* simple animation */ ADDRESS REAL3D0 do i = 1 to 10 /* ten frames */ 0 O_GETROOT /* objects to be moved */ 0.10 0 0 M_MOVE /* move 0.1, 0 0 units */ RENDER /* render the frame */ end As mentioned earlier, the ARexx interface of REAL 3D can be expanded simply by writing new RPL words. For example, the animation presented - REFERENCE 6.2 - in the previoUs example can be implemented by defining a following RPL word in REAL 3D. ( execute this as a macro from REAL 3D ) ( or insert it to s:rpl-startup ) : MOVE_&_RENDER 0 0 GETROOT ( objects to be moved 0.1 0 0 0 M_MOVE ( move 0.1 0 0 units RENDER ( render the frame ; Then it is possible to execute the following ARexx macro: /* simple ARexx animation */ do i = 1 to 10 /* ten frames */ MOVE_&_RENDER /* call the new RPL word */ end In the previous examples, we used ARexx control structures for defining a simple animation loop. However, the same animation can be created by using the control structures of RPL. In other words, the RPL word can also contain the loop definition. Execute the following RPL program as a Macro from REAL 3D: : ANIMATE 10 0 DO ( call a word defined earlier ) MOVE_&_RENDER LOOP ; Now send the following ARexx command to REAL 3D: rx "ADDRESS REAL3D0 ANIMATE" and all obJects will be moved and rendered ten times. The third way to create the same animation is to send a small RPL program to REAL 3D which takes care of everything: /* define a new RPL word through ARexx */ ADDRESS REAL3D0 ":ANIMALL 10 0 DO 0 O_GETROOT 0.1 0 0 0 M_MOVE RENDER LOOP ;" Then send the "ANIMALL" command to REAL 3D: rx "ADDRESS REAL3D0 ANIMALL" Note that if the syntax of a RPL program is not accepted by the ARexx interpreter, it must be quoted . When the ARexx sends the string to the host application it removes double quotes making it a valid RPL program. 6.4 Return Values REAL 3D returns 0 if it succeeds in its task to execute an ARexx command. Otherwise it returns a positive value. ARexx assigns this return value to the variable "rc". You can use this variable to detect whether or not the command succeeded. /* return value testing example */ address REAL3D0 ZENDER /* send command to Real */ if(rc ~= 0) then do /* test return value */ say "Cannot ZENDER" exit rc end Note that REAL 3D uses the return value only for indicating whether or not the executed command succeeded. One of the most common errors is "syntax error" in the RPL program; the ARexx program has sent a command or program to REAL 3D which RPL cannot understand. Because the return value is only used as an error indicator, the only way to affect the return value is the RPL word ERROR. In other words, the called RPL word can cause an error itself, making REAL 3D return an error code to the ARexx program. - REFERENCE 6.3 - ( Define this RPL word in REAL 3D ) : MAKE_SURE "YESlNO" "Are You Sure" GET_KEY IF QUIT ( if "YES" selected, return 0 ) ELSE ( otherwise cause error ) 0 ERROR ( without error message ) ENDIF ; Now the new RPL word can be called from any ARexx program as follows: /* test return value example */ address REAL3D0 MAKE_SURE if(rc ~= 0) then do say "The user selected NO" exit rc end say "The user selected YES" 6.5 Result String When a simple "error/no error" return value is not enough, ARexx programs can ask REAL 3D to return additional information about the executed command. So called "result string" can be used for that purpose. REAL 3D returns a result string only if it is requested by the ARexx program and if Real successfully executed the command. Therefore you always have to check the return value assigned to the variable "rc" before accessing the result string. You can request REAL 3D to pass a result string by using the ARexx instruction OPTIONS RESULTS, and the RPL word RX RESULT can be used for defining the result siring REAL 3D should return. For instance, an ARexx program could ask REAL 3D to ask the name of the user. This can be accomplished by defining the following word in REAL 3D: ( Execute me as a macro ) : WHO_ARE_YOU ( put user's name to the result string ) RX_RESULT 50 "Who Are You ?" GET_STR ( return error if user ) ( cancelled the requester ) NOT IF 0 ERROR ENDIF ; The ARexx program sending WHO_ARE_YOU command to Real looks like the following: /* request result string */ options results /* define host address */ address REAL3D0 /* send command to REAL 3D */ WHO_ARE_YOU /* check return value and exit */ /* if the user selected cancel */ if(rc ~= 0) then do say "Unknown Person" exit rc end /* otherwise "result" variable contains */ /* the name of the user */ say result Although ARexx allows you to mix RPL programs with ARexx programs (if ARexx cannot recognize a part of the program, it assumes it to be an external procedure call and sends it to the host application), a better solution is to keep RPL programs and ARexx macros separated. This can be implemented so that the ARexx macro asks REAL 3D to load the required RPL programs in as the first thing. For example, the previous WHO_ARE_YOU example could be implemented as follows: - REFERENCE 6.4 - /* ask Real to load whoareyou.rpl */ /* before calling word WHO_ARE_YOU */ ADDRESS REAL3D0 "ram:whoareyou.rpl" LOAD WHO_ARE_YOU if(rc ~= 0)then do say "Unknown Person" exit rc end say result As you have propably already noticed, ARexx allows you to use apostrophes (") for passing quoted strings to host applications. Whenever you have to send a string to REAL 3D, you have to enclose it with apostrophes because of the way ARexx translates them. ARexx translates "/car/engine" 0_FIND to /car/engine O_FIND which will cause a syntax error when sent to REAL 3D. Another possiblity is to use a variable as follows: objname = "/car/engine" " II objname II " O_FIND 6.6 Clip List Multiple result strings can be passed to an ARexx program by using the Clip List feature of the ARexx. The Clip List consists of pairs of strings where each entry consists of a name and a value. REAL 3D can access the Clip List using the word RX_SETCLIP and ARexx programs using the function getclip() and setclip(). For example, REAL 3D can add one entry to the Clip List as follows: "rad" "0.5" RX_SETCLIP Then the Arexx program can read it as follows: radius = getclip("rad") Clip List is typically used whenever two or more result strings are needed. For example, the ARexx program could ask REAL 3D to assign the name of the current level and root objects to the clip list. The RPL program would look like this: ( save this program as ram:clexample.rpl ) : ASK_CURR_ROOT "root" ( Clip List item name ) ( and address of the object name: ) O_GETROOT O.sName + RX_SETCLIP "current" O_GETCURR O.sName RX_SETCLIP ; The actual ARexx macro asks REAL 3D to load clexample.rpl in and then calls the word ASK_CURR_ROOT which causes Real to assign values to "root" and "current items in the Clip List. /* ARexx macro */ ADDRESS REAL3D0 /* ask Real to load clexample.rpl in */ "ram:clexample.rpl" LOAD /* call the word defined in clexample */ ASK_CURR_ROOT say getclip("root") say getclip("current") 6.7 Sending ARexx Commands from REAL 3D As already mentioned, REAL 3D can send and receive ARexx commands. This can be accomplished by using the RPL word RX. The RX word takes one parameter, which is a string containing the ARexx program to be executed. - REFERENCE 6.5 - For example: "ADDRESS COMMAND dir" RX causes ARexx to send the "dir" command to the underlying AmigaDOS shell when entered from any RPL window. The command: "RENDER" RX causes all REAL 3D windows to be rendered as if the RENDER command was received from the external application or typed in from any RPL window. Note that ARexx allows you to use apostrophes (") for passing quoted strings to host applications. In RPL, you can use use the backspace character before the double quote character. This allows you to send strings with double quotes to the ARexx master process. For example: "\"hello world\" PUTS" RX does the same as the command "hello world" PUTS when typed in from a RPL window. Lets consider the following scenario: the user is going to render an animation which consists of 1000 frames. Because there is not enough disk space for such a big animation, the only possibility is to render the animation directly to video through a single frame recorder. Naturally the software which controls the single frame recorder supports ARexx and can therefore communicate with REAL 3D without any problems. The "frame command" in the Animation window can be used for that purpose. Lets assume that the user has written a ARexx macro which saves the rendered imagefile to video. If the name of the ARexx program is "save.rexx", then the frame command would look like the following: "save.rexx" RX Whenever the REAL 3D gets a new image ready, the frame command is executed causing ARexx to run the "save.rexx" program saving the rendered image to the video tape. 6.8 Return Values From Other Applications Just as REAL 3D can pass a return value to an ARexx program, other applications can return result values to REAL 3D. Because some applications use return values for indicating something else than just error situations, return values are not automatically interpreted as errors by RPL. The word RX_Rc word can be used for fetching the return value from an executed ARexx command. For example: ( Simple RPL program sending an ARexx ) ( command to another application ) : RC_TEST ( send ARexx command : "ADDRESS ABCD Hi There" RX RX_RC @ ( fetch return value IF ( if return value is not zero "ARexx command failed" PUTS ELSE "Arexx command succeeded" PUTS ENDIF ; - REFERENCE 6.6 - In this example, the execution of the RPL program is not terminated if the ARexx command failed. However , if the error situation is fatal and the RPL program should not continue at all, the ERROR word can be used for terminating the RPL program. ( Terminate the program if ) ( ARexx command fails ) : RC_TEST ( send ARexx command: "ADDRESS ABCD Hi There" RX RX_RC @ IF "Cannot execute ARexx command" ERROR ENDIF ; Note that you can use RX RC only for checking what kind of return values the called external application returned. You cannot use it for affecting the return value REAL 3D passes to the caller application which has sent an ARexx message to REAL 3D's port. REAL 3D always returns 0 if the executed command succeeded and a positive value if it failed. In order to return more information to the caller application, use result strings or the Clip List. 6.9 Result Strings from Other Applications ARexx commands sent by REAL 3D can return information from eternal applications through "result string" much the same way as REAL 3D can return result strings to eternal applications. The result string can be accessed using the RPL word RX_RESULT. For example, lets imagine that the user starts an external application whose ARexx port name is EXTAPP and which supports the ARexx command called WEEK_DAY. This command returns the result string containing the current day of week. The RPL program could look like this: ( RPL program which asks the current day ) : DAY ( send ARexx command ) "ADDRESS EXTAPP WEEK_DAY" RX ( check the return value ) RX_RC @ IF "Cannot get day" ERROR ENDIF ( print out the result string ) RX_RESULT PUTS ; For more information about all ARexx oriented RPL words, see the RPL reference chapter 4.10 AREXX WORDS. - REFERENCE 6.7 - Appendix A PREDEFINED ICONS. ---------------------------- Figure: AA-1 (PICTURE: AA-1) Figure: AA-2 (PICTURE: AA-2) Appendix B HOT KEYS AND MENUS ----------------------------- SYMBOLS USED FOR HOT-KEY DESCRIPTIONS <CTRL> - control key <ALT > - either alt key <SHIFT> - either shift key <LAM> - left Amiga key <RAM> - right Amiga key <ENTER> - enter or return key <SPACE> - space bar <TAB> - tab key <BSP> - backspace key <DEL> - delete key <ESC> - escape key <LMB> - left mouse button < RMB> - right mouse button <DRAG> - use OS 2.0 drag box <CLK> - cursor left key <CRK> - cursor right key <CUK> - cursor up key <CDK> - cursor down key , - keys must be pressed in sequence There are three levels of keyboard support: Immediate Menu Function RPL Key Binding IMMEDIATE HOT-KEY ACTIONS Certain actions are invoked only by hot-keys, there are no menu equivalents. The following are the immediate hot-key actions: VIEW COORDINATE CONTROL ViewPoint Rotation - rotation of viewpoint around aimpoint: <CUK> & <CDK> - Tilt <CLK> & <CRK> - Pan <SHIFT><CLK> & <SHIFT><CRK> - Roll ViewPoint Movement: <ALT><CLK> & <ALT><CRK> - X axis <ALT><CUK> & <ALT><CDK> - Y axis <SHIFT><ALT><CLK> & <SHIFT><ALT><CRK> - Z axis SPECIALS <ESC> - Cancel all <SPACE> - Cancel refresh <ENTER> - Refresh MOUSE ACTION MODIFIERS <LMB><CTRL> - Defines a new coordinate but leaves System Hot- Point unaltered. <LMB><ALT> - Push coordinates onto Vector Stack <DRAG> - Performs an Average All action on all points contained within the drag box <DRAG> <SHIFT> - Push points onto Vector Stack <DRAG><ALT> - Average All with points from selected objects - APPENDIX B.1 - <DRAG><SHIFT><ALT> - Push points from selected objects <DRAG><CTRL><SHIFT> - Automatic group creation <DRAG><CTRL><SHIFT><ALT>- Automatic group creation with selected objects CREATION HOT-KEYS <BSP> - Close curve <TAB> - Average coordinates in object creation (find centre) MACRO ARD SUPPORT SINGLE-KEY MACROS: Configurable. See the file "RPL-startup" MENU HOT-KEYS The following list shows the current Menu functions and corresponding hot-keys. Also the menu numbers are listed here; use these numbers when using MENU word of RPL to define custom key bindings. MAINMENU Function Hot-key RPL MENU Code PROJECT/ Objects/ Insert 0 0 0 Save 0 0 1 Replace 0 0 2 Project/ New 0 1 0 Insert 0 1 2 Save 0 1 3 Replace 0 1 4 Insert Sections 0 1 6 Save Sections 0 1 7 Replace Sections 0 1 8 Materials/ Window <RAM>m 0 2 0 Delete 0 2 2 Delete_All 0 2 3 Insert 0 2 5 Save 0 2 6 Replace 0 2 7 Macros/ * Record_Macro 0 3 0 Execute_Current 0 3 2 Execute_Named 0 3 3 Repeat_Current 0 3 4 Spread_Current 0 3 5 Current_to_Named 0 3 7 Named_to_Current 0 3 8 Named Colors/ Select 0 4 0 Create 0 4 1 Modify 0 4 2 Delete 0 4 3 Insert 0 4 5 Save 0 4 6 Replace 0 4 7 - APPENDIX B.2 - Function Hot-key RPL MENU Code Windows/ Select 0 5 0 View 0 5 1 View_Superbitmap 0 5 2 View_Borderless 0 5 3 View_DBuffered 0 5 4 RPL 0 5 5 Tools 0 5 6 Animation <RAM>a 0 5 7 Palette <RAM>p 0 5 8 Measuring 0 5 9 Screen 0 5 10 Close 0 5 12 * No Gadgets 0 5 13 Environment/ Open_Screen 0 6 0 Make_Def. Pub 0 6 1 Close_Screen 0 6 2 Close_Current 0 6 3 Insert 0 6 5 Save 0 6 6 Replace 0 6 7 Save_Screen 0 6 9 Screen_Palette 0 6 10 External Screen/ Open 0 7 0 Close 0 7 1 Set_Modes 0 7 2 Settings 0 7 3 Save 0 7 4 Exit_Real 0 8 0 CREATE/ Visibles Polygon 1 0 0 Polyhedron 1 0 1 Polymid 1 0 2 Cut_polymid 1 0 3 Rectangle 1 0 5 Cube 1 0 6 pyramid 1 0 7 Cut_pyramid 1 0 8 Reg.polygon 1 0 10 Reg.polyhedr. 1 0 11 Reg.polymid 1 0 12 Reg.cut.plmd 1 0 13 Circle 1 0 15 3P_Circle 1 0 16 Cylinder 1 0 17 Cone 1 0 18 Cutcone 1 0 19 Sphere 1 0 21 Ellipsoid 1 0 22 Ellipsegment 1 0 23 Cut_ellipseg 1 0 24 Hyperbol 1 0 26 Cut_hyperb. 1 0 27 Sectors/ Circle 1 1 0 Cylinder 1 1 1 Cone 1 1 2 Cut_cone 1 1 3 Ellipsegment 1 1 5 Cut_ellipseg. 1 1 6 Hyperbol 1 1 8 Cut_hyperbol 1 1 9 Structure/ Level 1 2 0 Link 1 2 1 Group 1 2 2 Method 1 2 3 Light-sources/ Point 1 3 0 Line 1 3 1 Wall 1 3 2 Controls/ Attribute 1 4 0 Offset 1 4 1 Axis 1 4 2 Coordsys 1 4 3 Open_Line 1 4 5 Closed_Line 1 4 6 Circular_Line 1 4 7 - APPENDIX B.3 - Function Hot-key RPL MENU Code B-Spline_Ctrlp 1 4 9 B-Spline_Knot 1 4 10 B-Spline_Curve 1 4 11 B-Spline_Closed 1 4 12 B-Spline_Cir. 1 4 13 B-Spline_Helix 1 4 14 Mapping/ Default 1 5 0 Parallel 1 5 1 Cylinder 1 5 2 Sphere 1 5 3 Disk 1 5 4 Observers/ Viewpoint 1 6 0 Aimpoint 1 6 1 Compound_Tools/ Lathe 1 7 0 Circular_Subdivided 1 7 2 Rounded_Circ._Subd. 1 7 3 Sharp_Circular 1 7 4 Rounded_Circular 1 7 5 Conical 1 7 7 Conical_Subdivided 1 7 8 Rectangular 1 7 10 Rectangular_Subdiv. 1 7 11 Rectangular_Conical 1 7 12 Rect.Conical_Subd. 1 7 13 Rounded_Polygon 1 7 15 Rounded_Polyhedron 1 7 16 Ellipsed_Polygon 1 7 17 Ellipsed_Polyhedron 1 7 18 Join_Primitives 1 7 20 ObJect-Pixel_Tool 1 7 21 Freeform/ Mesh 1 8 0 Coplanar 1 8 2 Orthogonal 1 8 3 Rotate 1 8 4 Swing/Move 1 8 5 Swing/Size 1 8 6 Build from Curves 1 8 7 MeshPixel_ Tool 1 8 8 Fractals/ Landscape 1 9 0 Tree 1 9 1 Boolean/ OR 1 10 0 AND 1 10 1 AND_NOT 1 10 2 AND_with_Paint 1 10 3 AND_NOT_with_Paint 1 10 4 Rethink 1 10 6 Rethink_All 1 10 7 Unthink 1 10 8 Unthink_All 1 10 9 MODIFY/ Linear/ Move 2 0 0 Move_COG 2 0 1 Size_2D 2 0 2 Size_3D 2 0 3 Stretch 2 0 4 Extend 2 0 5 Rotate 2 0 6 Mirror 2 0 7 Shear 2 0 8 Rot&Ext 2 0 9 Deform 2 0 10 Structure/ Cut 2 1 0 Copy 2 1 1 Paste 2 1 2 Delete 2 1 3 Duplicate 2 1 4 Swap 2 1 5 Properties/ Color 2 2 0 Name 2 2 1 Attributes 2 2 2 Alpha Channel 2 2 3 Tags 2 2 4 Animation 2 2 5 Replace_Tags 2 2 6 COG 2 2 7 Direction 2 2 8 Velocity 2 2 9 Spin 2 2 10 Size 2 2 11 - APPENDIX B.4 - Function Hot-key RPL MENU Code Bend_Local/ Move_2D 2 3 0 Move_3D 2 3 1 Move_Radial 2 3 2 Size_2D 2 3 4 Size_3D 2 3 5 Size_Radial 2 3 6 Bend Global/ Move_2D 2 4 0 Move_3D 2 4 1 Move_Radial 2 4 2 Size_2D 2 4 4 Size_3D 2 4 5 Size_Radial 2 4 6 Bend_Endp./ Move_2D 2 5 0 Move_3D 2 5 1 Move_Radial 2 5 2 Size_2D 2 5 4 Size_3D 2 5 5 Size_Radial 2 5 6 Bend Linear Move_2D 2 6 0 Move_3D 2 6 1 Move_Radial 2 6 2 Size_2D 2 6 4 Size_3D 2 6 5 Size_Radial 2 6 6 Non-linear/ Move 2 7 0 Size 2 7 1 Stretch 2 7 2 Rotate 2 7 3 * Parabola 2 7 5 * Linear 2 7 6 * Circle 2 7 7 * Sine 2 7 8 * Curve 2 7 9 Set_Tool 2 7 11 Special/ Project_to_Object 2 8 0 Inverse_Kinematic 2 8 1 COGs/ Size_2D 2 9 0 Size_3D 2 9 1 Stretch 2 9 2 Extend 2 9 3 Rotate 2 9 4 Mirror 2 9 5 Shear 2 9 6 Rot&Ext 2 9 7 About COGs/ Size_2D 2 10 0 Size_3D 2 10 1 Stretch 2 10 2 Extend 2 10 3 Rotate 2 10 4 Mirror 2 10 5 Shear 2 10 6 Rot&Ext 2 10 7 Freeform/ Reparametrize 2 11 0 Move_Knotpoint <RAM>k 1 11 1 Concatenate 2 11 2 Swap_Direction 2 11 3 Open/Close 2 11 4 Type 2 11 5 Invert 2 11 6 Remap 2 11 7 Surf.to_curves 2 11 8 Distribute 2 11 9 Assign 2 11 10 xchange_u_&_v 2 11 11 Snap to 2 11 12 Delete 2 11 13 Insert 2 11 14 Break 2 11 15 Draw Mode/ * Accurate 2 12 0 * Bounding_box 2 12 1 - APPENDIX B.5 - Function Hot-key RPL MENU Code VIEW/ Type/ * Parallel 3 0 0 * Perspective 3 0 1 * Separate IO 3 0 3 Input Crd/ Set_XY <RAM>x 3 1 0 Set_YZ <RAM>y 3 1 1 Set_ZX <RAM>z 3 1 2 Set_Custom <RAM>c 3 1 3 Set_Origin 3 1 4 Define_X 3 1 5 Define_Y 3 1 6 ObJect_Space->View 3 1 7 Camera/ Forwards <RAM>f 3 2 0 Backwards <RAM>b 3 2 1 Orientation 3 2 2 View->Camera <RAM>v 3 2 3 Camera->View <RAM>w 3 2 4 Create_Camera 3 2 5 * Camera_View 3 2 7 Display/ Zoom_In <RAM>+ 3 3 0 Zoom_Out <RAM>- 3 3 1 Custom_Scale 3 3 2 Position 3 3 3 Pos&Zoom_In <RAM>i 3 3 4 Pos&Zoom_Out <RAM>o 3 3 5 Reset <RAM>e 3 3 6 Auto focus 3 3 7 Grid/ Select 3 4 0 Create 3 4 1 Modify 3 4 2 Reposition 3 4 3 Delete 3 4 4 * Visible 3 4 6 * Snap_to_Grid 3 4 7 Render/ Window <RAM>r 3 5 0 Boxes <RAM>t 3 5 1 Greyscale <RAM>g 3 5 3 HAM <RAM>h 3 5 4 * Selected 3 5 6 Settings <RAM>s 3 5 7 Export_RPL 3 5 9 Render_Hierarchy 3 5 10 Drawing_Set <RAM>d 3 6 0 Boxes/ Define 3 7 0 Modify 3 7 1 Delete 3 7 2 Delete_All 3 7 3 Show_All 3 7 4 ANIMATE/ Create/ Path 4 0 0 Direction 4 0 1 Rotation 4 0 2 Sweep 4 0 3 Stretch 4 0 4 Size 4 0 5 RPL 4 0 6 Control/ Play_Forwards 4 1 0 Play_Backwards 4 1 1 Go_to_Beginning 4 1 2 Go_to_End 4 1 3 Go_to_? 4 1 4 Step_Forwards 4 1 5 Step_Backwards 4 1 6 Refresh 4 1 8 - APPENDIX B.6 - Function Hot-key RPL MENU Code EXTRAS/ Vectors/ Push 5 0 0 Pull <RAM>. 5 0 1 Enter 5 0 2 Clear 5 0 3 Add 5 0 5 Subtract 5 0 6 Average 5 0 7 Average_All 5 0 8 Cross_Product 5 0 9 Eval._Current 5 0 11 Define_&_Eval. 5 0 12 Length_evaluate 5 0 13 Lasso 5 0 15 Undo <RAM>u 5 1 0 Statistics 5 2 0 Refresh_All/ Wire-frame 5 3 0 Ray_Trace 5 3 1 Cancel_All <ESC> 5 4 0 Evaluate/ Curve_Length 5 5 0 Parameter 5 5 1 Select_Objects <RAM><SPACE> 5 6 0 Free_Images 5 7 0 SETTINGS/ Clip Boxes/ * Active 5 0 0 Select 5 0 2 Deselect 5 0 3 General 5 1 0 Refresh/ * None 5 2 0 * Current 5 2 1 * All 5 2 2 Oper.Level/ * Active 5 3 0 Depth 5 3 2 Creation/ * Qry._Level_Name 5 4 0 * Qry._Prim._Name 5 4 1 * Auto_current 5 4 2 * Auto_selected 5 4 3 * Auto_index 5 4 4 Paths 5 5 0 Alpha_Channel 5 6 0 Attributes 5 7 0 RPL 5 8 0 View Resolutions/ Rotation 5 9 0 Position 5 9 1 Zoom 5 9 2 Undo/ * Active 5 10 0 Set_Depth 5 10 1 Clear 5 10 2 File Icons 5 10 3 TOOLS/ Icons/ * Visibles 6 0 0 * Sectors 6 0 1 * Structures 6 0 2 * Lights 6 0 3 * Controls 6 0 4 * Compounds 6 0 5 * Freef.Tools 6 0 6 * Booleans 6 0 7 * Mod/Linear 6 0 8 * Mod/Structure 6 0 9 Create_Icon 6 1 0 Delete_Icon 6 2 0 MATERIAL WINDOW MENU DEFINE/ Texture <RAM>d Show_Image <RAM>s Transp._Color <RAM>c Tags <RAM>t END OF PART 6